procyberian/emacs
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

*** empty log message ***

Browse source
This commit is contained in:
Richard M. Stallman 1998-05-19 03:45:57 +00:00
parent c6d6572475
commit a9f0a989a1
45 changed files with 2421 additions and 1209 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

242
lispref/advice.texi
View file

@ -8,25 +8,96 @@
@cindex advising functions
The @dfn{advice} feature lets you add to the existing definition of a
function, by @dfn{advising the function}. This a clean method for a
function, by @dfn{advising the function}. This is a clean method for a
library to customize functions defined by other parts of Emacs---cleaner
than redefining the function in the usual way.
than redefining the whole function.
Each piece of advice can be enabled or disabled explicitly. The
enabled pieces of advice for any given function actually take effect
when you activate advice for that function, or when that function is
subsequently defined or redefined.
@strong{Usage Note:} Advice is useful for altering the behavior of
existing calls to an existing function. If you want the new behavior
for new calls, or for key bindings, it is cleaner to define a new
function (or a new command) which uses the existing function.
@menu
* Defining Advice::
* Computed Advice::
* Activation of Advice::
* Enabling Advice::
* Preactivation::
* Argument Access in Advice::
* Combined Definition::
* Simple Advice:: A simple example to explain the basics of advice.
* Defining Advice:: Detailed description of @code{defadvice}.
* Computed Advice:: ...is to @code{defadvice} as @code{fset} is to @code{defun}.
* Activation of Advice:: Advice doesn't do anything until you activate it.
* Enabling Advice:: You can enable or disable each piece of advice.
* Preactivation:: Preactivation is a way of speeding up the
loading of compiled advice.
* Argument Access:: How advice can access the function's arguments.
* Subr Arguments:: Accessing arguments when advising a primitive.
* Combined Definition:: How advice is implemented.
@end menu
@node Simple Advice
@section A Simple Advice Example
The command @code{next-line} moves point down vertically one or more
lines; it is the standard binding of @kbd{C-n}. When used on the last
line of the buffer, this command inserts a newline to create a line to
move to (if @code{next-line-add-newlines} is non-@code{nil}).
Suppose you wanted to add a similar feature to @code{previous-line},
which would insert a new line at the beginning of the buffer for the
command to move to. How could you do this?
You could do it by redefining the whole function, but that is not
modular. The advice feature provides a cleaner alternative: you can
effectively add your code to the existing function definition, without
actually changing or even seeing that definition. Here is how to do
this:
@example
(defadvice previous-line (before next-line-at-end (arg))
"Insert an empty line when moving up from the top line."
(if (and next-line-add-newlines (= arg 1)
(save-excursion (beginning-of-line) (bobp)))
(progn
(beginning-of-line)
(newline))))
@end example
@cindex piece of advice
This expression defines a @dfn{piece of advice} for the function
@code{previous-line}. This piece of advice is named
@code{next-line-at-end}, and the symbol @code{before} says that it is
@dfn{before-advice} which should run before the regular definition of
@code{previous-line}. @code{(arg)} specifies how the advice code can
refer to the function's arguments.
When this piece of advice runs, it creates an additional line, in the
situation where that is appropriate, but does not move point to that
line. This is the correct way to write the advice, because the normal
definition will run afterward and will move back to the newly inserted
line.
Defining the advice doesn't immediately change the function
@code{previous-line}. That happens when you @dfn{activate} the advice,
like this:
@example
(ad-activate 'previous-line)
@end example
@noindent
This is what actually begins to use the advice that has been defined so
far for the function @code{previous-line}. Henceforth, whenever that
function is run, whether invoked by the user with @kbd{C-p} or
@kbd{M-x}, or called from Lisp, it runs the advice first, and its
regular definition second.
This example illustrates before-advice, which is one @dfn{class} of
advice: it runs before the function's base definition. There are two
other advice classes: @dfn{after-advice}, which runs after the base
definition, and @dfn{around-advice}, which lets you specify an
expression to wrap around the invocation of the base definition.
@node Defining Advice
@section Defining Advice
@ -50,16 +121,11 @@ form) to be advised. From now on, we will write just ``function'' when
describing the entity being advised, but this always includes macros and
special forms.
The argument @var{name} is the name of the advice, a non-@code{nil}
symbol. The advice name uniquely identifies one piece of advice, within all
the pieces of advice in a particular class for a particular
@var{function}. The name allows you to refer to the piece of
advice---to redefine it, or to enable or disable it.
Where an ordinary definition has an argument list, an advice definition
needs several kinds of information.
@var{class} specifies the class of the advice---one of @code{before},
@cindex class of advice
@cindex before-advice
@cindex after-advice
@cindex around-advice
@var{class} specifies the @dfn{class} of the advice---one of @code{before},
@code{after}, or @code{around}. Before-advice runs before the function
itself; after-advice runs after the function itself; around-advice is
wrapped around the execution of the function itself. After-advice and
@ -75,6 +141,15 @@ definition is never run. This provides a way to override the original
definition completely. (It also overrides lower-positioned pieces of
around-advice).
The argument @var{name} is the name of the advice, a non-@code{nil}
symbol. The advice name uniquely identifies one piece of advice, within all
the pieces of advice in a particular class for a particular
@var{function}. The name allows you to refer to the piece of
advice---to redefine it, or to enable or disable it.
In place of the argument list in an ordinary definition, an advice
definition calls for several different pieces of information.
The optional @var{position} specifies where, in the current list of
advice of the specified @var{class}, this new advice should be placed.
It should be either @code{first}, @code{last} or a number that
@ -84,35 +159,49 @@ no position is specified, the default is @code{first}. The
advice.
The optional @var{arglist} can be used to define the argument list for
the sake of advice. This argument list should of course be compatible
with the argument list of the original function, otherwise functions
that call the advised function with the original argument list in mind
will break. If more than one piece of advice specifies an argument
list, then the first one (the one with the smallest position) found in
the list of all classes of advice will be used.
the sake of advice. This becomes the argument list of the combined
definition that is generated in order to run the advice (@pxref{Combined
Definition}). Therefore, the advice expressions can use the argument
variables in this list to access argument values.
@var{flags} is a list of symbols that specify further information about
how to use this piece of advice. Here are the valid symbols and their
meanings:
This argument list must be compatible with the argument list of the
original function, so that it can handle the ways the function is
actually called. If more than one piece of advice specifies an argument
list, then the first one (the one with the smallest position) found in
the list of all classes of advice is used. Numbers outside the range
are mapped to the beginning or the end, whichever is closer.
The remaining elements, @var{flags}, is a list of symbols that specify
further information about how to use this piece of advice. Here are the
valid symbols and their meanings:
@table @code
@item activate
Activate all the advice for @var{function} after making this definition.
This is ignored when @var{function} itself is not defined yet (which is
known as @dfn{forward advice}).
Activate the advice for @var{function} now. Changes in a function's
advice always take effect the next time you activate advice for the
function; this flag says to do so, for @var{function}, immediately after
defining this piece of advice.
@cindex forward advice
This flag has no effect if @var{function} itself is not defined yet (a
situation known as @dfn{forward advice}), because it is impossible to
activate an undefined function's advice. However, defining
@var{function} will automatically activate its advice.
@item protect
Protect this piece of advice against non-local exits and errors in
preceding code and advice.
preceding code and advice. Protecting advice makes it a cleanup in an
@code{unwind-protect} form, so that it will execute even if the
previous code gets an error or uses @code{throw}. @xref{Cleanups}.
@item compile
Says that the combined definition which implements advice should be
byte-compiled. This flag is ignored unless @code{activate} is also
specified.
Compile the combined definition that is used to run the advice. This
flag is ignored unless @code{activate} is also specified.
@xref{Combined Definition}.
@item disable
Disable this piece of advice, so that it will not be used
unless subsequently explicitly enabled.
Initially disable this piece of advice, so that it will not be used
unless subsequently explicitly enabled. @xref{Enabling Advice}.
@item preactivate
Activate advice for @var{function} when this @code{defadvice} is
@ -124,10 +213,10 @@ This is useful only if this @code{defadvice} is byte-compiled.
@end table
The optional @var{documentation-string} serves to document this piece of
advice. If the @code{documentation} function gets the documentation
for @var{function} when its advice is active, the result will combine
the documentation strings of all the advice with that of the original
function.
advice. When advice is active for @var{function}, the documentation for
@var{function} (as returned by @code{documentation}) combines the
documentation strings of all the advice for @var{function} with the
documentation string of its original function definition.
The optional @var{interactive-form} form can be supplied to change the
interactive behavior of the original function. If more than one piece
@ -162,7 +251,9 @@ this form:
@end example
Here @var{protected} and @var{enabled} are flags, and @var{definition}
is an expression that says what the advice should do.
is the expression that says what the advice should do. If @var{enabled}
is @code{nil}, this piece of advice is initially disabled
(@pxref{Enabling Advice}).
If @var{function} already has one or more pieces of advice in the
specified @var{class}, then @var{position} specifies where in the list
@ -194,11 +285,12 @@ redefining the function over and over as each advice is added. More
importantly, it permits defining advice for a function before that
function is actually defined.
When a function is first activated, its original definition is saved,
and all enabled pieces of advice for that function are combined with the
original definition to make a new definition. This definition is
installed, and optionally byte-compiled as well, depending on conditions
described below.
When a function's advice is first activated, the function's original
definition is saved, and all enabled pieces of advice for that function
are combined with the original definition to make a new definition.
(Pieces of advice that are currently disabled are not used; see
@ref{Enabling Advice}.) This definition is installed, and optionally
byte-compiled as well, depending on conditions described below.
In all of the commands to activate advice, if @var{compile} is @code{t},
the command also compiles the combined definition which implements the
@ -208,9 +300,9 @@ advice.
This command activates the advice for @var{function}.
@end deffn
To activate a function whose advice is already active is not a no-op.
It is a useful operation which puts into effect any changes in advice
since the previous activation of the same function.
To activate advice for a function whose advice is already active is not
a no-op. It is a useful operation which puts into effect any changes in
advice since the previous activation of that function's advice.
@deffn Command ad-deactivate function
This command deactivates the advice for @var{function}.
@ -239,15 +331,21 @@ function which has at least one piece of advice that matches
@deffn Command ad-update-regexp regexp &optional compile
This command activates pieces of advice whose names match @var{regexp},
but only those that are already activated.
@end deffn
but only those for functions whose advice is already activated.
@deffn Command ad-stop-advice
Turn off automatic advice activation when a function is defined or
redefined.
Reactivating a function's advice is useful for putting into effect all
the changes that have been made in its advice (including enabling and
disabling specific pieces of advice; @pxref{Enabling Advice}) since the
last time it was activated.
@end deffn
@deffn Command ad-start-advice
Turn on automatic advice activation when a function is defined or
redefined. If you turn on this mode, then advice really does
take effect immediately when defined.
@end deffn
@deffn Command ad-stop-advice
Turn off automatic advice activation when a function is defined or
redefined.
@end deffn
@ -275,8 +373,8 @@ the function @code{foo}:
(ad-disable-advice 'foo 'before 'my-advice)
@end example
This call by itself only changes the enable flag for this piece of
advice. To make this change take effect in the advised definition, you
This function by itself only changes the enable flag for a piece of
advice. To make the change take effect in the advised definition, you
must activate the advice for @code{foo} again:
@example
@ -293,8 +391,10 @@ This command enables the piece of advice named @var{name} in class
@var{class} on @var{function}.
@end deffn
You can also disable many pieces of advice at once using a regular
expression.
You can also disable many pieces of advice at once, for various
functions, using a regular expression. As always, the changes take real
effect only when you next reactivate advice for the functions in
question.
@deffn Command ad-disable-regexp regexp
This command disables all pieces of advice whose names match
@ -322,12 +422,12 @@ same function, and the function's own definition. If the
@code{defadvice} is compiled, that compiles the combined definition
also.
When the function is subsequently activated, if the enabled advice for
the function matches what was used to make this combined
definition. then the existing combined definition is used, and there is
no need to construct one. Thus, preactivation never causes wrong
When the function's advice is subsequently activated, if the enabled
advice for the function matches what was used to make this combined
definition, then the existing combined definition is used, thus avoiding
the need to construct one. Thus, preactivation never causes wrong
results---but it may fail to do any good, if the enabled advice at the
time of activation doesn't match.
time of activation doesn't match what was used for preactivation.
Here are some symptoms that can indicate that a preactivation did not
work properly, because of a mismatch.
@ -351,8 +451,8 @@ when you @emph{compile} the preactivated advice.
There is no elegant way to find out why preactivated advice is not being
used. What you can do is to trace the function
@code{ad-cache-id-verification-code} (with the function
@code{trace-function-background}) before the advised function is
activated. After activation, check the value returned by
@code{trace-function-background}) before the advised function's advice
is activated. After activation, check the value returned by
@code{ad-cache-id-verification-code} for that function: @code{verified}
means that the preactivated advice was used, while other values give
some information about why they were considered inappropriate.
@ -376,6 +476,13 @@ disadvantage: it is not robust, because it hard-codes the argument names
into the advice. If the definition of the original function changes,
the advice might break.
Another method is to specify an argument list in the advice itself.
This avoids the need to know the original function definition's argument
names, but it has a limitation: all the advice on any particular
function must use the same argument list, because the argument list
actually used for all the advice comes from the first piece of advice
for that function.
A more robust method is to use macros that are translated into the
proper access forms at activation time, i.e., when constructing the
advised definition. Access macros access actual arguments by position
@ -456,7 +563,8 @@ will be 3, and @var{r} will be @code{(2 1 0)} inside the body of
These argument constructs are not really implemented as Lisp macros.
Instead they are implemented specially by the advice mechanism.
@subsection Definition of Subr Argument Lists
@node Subr Arguments
@section Definition of Subr Argument Lists
When the advice facility constructs the combined definition, it needs
to know the argument list of the original function. This is not always

11
lispref/anti.texi
View file

@ -7,7 +7,7 @@
For those users who live backwards in time, here is information about
downgrading to Emacs version 19.34. We hope you will enjoy the greater
simplicity that results from the absence of many Emacs 19 features. In
simplicity that results from the absence of many Emacs 20 features. In
the following section, we carry this information back as far as Emacs
19.29, for which the previous printed edition of this manual was made.
@ -29,9 +29,10 @@ Within this range, there are no invalid character codes.
@item
The Custom facility has been replaced with a much simpler and more
general method of defining user option variables. Instead of
@code{defcustom}, which requires you to specify each user option's
data type and classify them into groups, all you have to do is write
a @code{defvar} and start the documentation string with @samp{*}.
@code{defcustom}, which requires you to specify each user option's data
type and classify options into groups, all you have to do is write a
@code{defvar}. You should still start the documentation string with
@samp{*}, though.
@end itemize
Here are changes in the Lisp language itself:
@ -138,7 +139,7 @@ directory name from the beginning of the file name---just like
We have got rid of the function @code{access-file}.
@item
Most of the minibuffer input functions, no longer take a default value as
Most of the minibuffer input functions no longer take a default value as
an argument. Also, they do not discard text properties from the result.
This means that if you insert text with text properties into the minibuffer,
the minibuffer value really will contain text properties.

12
lispref/backups.texi
View file

@ -289,7 +289,8 @@ This function returns a string that is the name to use for a
non-numbered backup file for file @var{filename}. On Unix, this is just
@var{filename} with a tilde appended.
The standard definition of this function is as follows:
The standard definition of this function, on most operating systems, is
as follows:
@smallexample
@group
@ -306,7 +307,9 @@ to prepend a @samp{.} in addition to appending a tilde:
@smallexample
@group
(defun make-backup-file-name (filename)
(concat "." filename "~"))
(expand-file-name
(concat "." (file-name-nondirectory filename) "~")
(file-name-directory filename)))
@end group
@group
@ -314,6 +317,11 @@ to prepend a @samp{.} in addition to appending a tilde:
@result{} ".backups.texi~"
@end group
@end smallexample
Some parts of Emacs, including some Dired commands, assume that backup
file names end with @samp{~}. If you do not follow that convention, it
will not cause serious problems, but these commands may give
less-than-desirable results.
@end defun
@defun find-backup-file-name filename

14
lispref/buffers.texi
View file

@ -47,9 +47,9 @@ not be displayed in any windows.
Buffers in Emacs editing are objects that have distinct names and hold
text that can be edited. Buffers appear to Lisp programs as a special
data type. You can think of the contents of a buffer as an extendable
string; insertions and deletions may occur in any part of the buffer.
@xref{Text}.
data type. You can think of the contents of a buffer as a string that
you can extend; 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
@ -112,7 +112,7 @@ the subroutine does not change which buffer is current (unless, of
course, that is the subroutine's purpose). Therefore, you should
normally use @code{set-buffer} within a @code{save-current-buffer} or
@code{save-excursion} (@pxref{Excursions}) form that will restore the
current buffer when your function is done . Here is an example, the
current buffer when your function is done. Here is an example, the
code for the command @code{append-to-buffer} (with the documentation
string abridged):
@ -201,8 +201,8 @@ An error is signaled if @var{buffer-or-name} does not identify an
existing buffer.
@end defun
@defspec save-current-buffer body...
@tindex save-current-buffer
@defmac save-current-buffer body...
The @code{save-current-buffer} macro saves the identity of the current
buffer, evaluates the @var{body} forms, and finally restores that buffer
as current. The return value is the value of the last form in
@ -215,8 +215,8 @@ of course. Instead, whichever buffer was current just before exit
remains current.
@end defmac
@tindex with-current-buffer
@defmac with-current-buffer buffer body...
@tindex with-current-buffer
The @code{with-current-buffer} macro saves the identity of the current
buffer, makes @var{buffer} current, evaluates the @var{body} forms, and
finally restores the buffer. The return value is the value of the last
@ -224,8 +224,8 @@ form in @var{body}. The current buffer is restored even in case of an
abnormal exit via @code{throw} or error (@pxref{Nonlocal Exits}).
@end defmac
@tindex with-temp-buffer
@defmac with-temp-buffer body...
@tindex with-temp-buffer
The @code{with-temp-buffer} macro evaluates the @var{body} forms
with a temporary buffer as the current buffer. It saves the identity of
the current buffer, creates a temporary buffer and makes it current,

72
lispref/commands.texi
View file

@ -332,6 +332,10 @@ Prompt.
@item F
A file name. The file need not exist. Completion, Default, Prompt.
@item i
An irrelevant argument. This code always supplies @code{nil} as
the argument's value. No I/O.
@item k
A key sequence (@pxref{Keymap Terminology}). This keeps reading events
until a command (or undefined command) is found in the current key
@ -408,6 +412,16 @@ Minibuffer}. Prompt.
@cindex evaluated expression argument
A Lisp form is read as with @kbd{x}, but then evaluated so that its
value becomes the argument for the command. Prompt.
@item z
A coding system name (a symbol). If the user enters null input, the
argument value is @code{nil}. @xref{Coding Systems}. Completion,
Existing, Prompt.
@item Z
A coding system name (a symbol)---but only if this command has a prefix
argument. With no prefix argument, @samp{Z} provides @code{nil} as the
argument value. Completion, Existing, Prompt.
@end table
@node Interactive Examples
@ -758,8 +772,15 @@ are characters or symbols; mouse events are always lists. This section
describes the representation and meaning of input events in detail.
@defun eventp object
This function returns non-@code{nil} if @var{object} is an input event.
A symbol
This function returns non-@code{nil} if @var{object} is an input event
or event type.
Note that any symbol might be used as an event or an event type.
@code{eventp} cannot distinguish whether a symbol is intended by Lisp
code to be used as an event. Instead, it distinguishes whether the
symbol has actually been used in an event that has been read as input in
the current Emacs session. If a symbol has not yet been so used,
@code{eventp} returns @code{nil}.
@end defun
@menu
@ -1314,6 +1335,36 @@ want to.
This kind of event indicates that the user deiconified @var{frame} using
the window manager. Its standard definition is @code{ignore}; since the
frame has already been made visible, Emacs has no work to do.
@cindex @code{mouse-wheel} event
@item (mouse-wheel @var{position} @var{delta})
This kind of event is generated by moving a wheel on a mouse (such as
the MS Intellimouse). Its effect is typically a kind of scroll or zoom.
The element @var{delta} describes the amount and direction of the wheel
rotation. Its absolute value is the number of increments by which the
wheel was rotated. A negative @var{delta} indicates that the wheel was
rotated backwards, towards the user, and a positive @var{delta}
indicates that the wheel was rotated forward, away from the user.
The element @var{position} is a list describing the position of the
event, in the same format as used in a mouse-click event.
This kind of event is generated only on some kinds of systems.
@cindex @code{drag-n-drop} event
@item (drag-n-drop @var{position} @var{files})
This kind of event is generated when a group of files is
selected in an application outside of Emacs, and then dragged and
dropped onto an Emacs frame.
The element @var{position} is a list describing the position of the
event, in the same format as used in a mouse-click event, and
@var{files} is the list of file names that were dragged and dropped.
The usual way to handle this event is by visiting these files.
This kind of event is generated, at present, only on some kinds of
systems.
@end table
If one of these events arrives in the middle of a key sequence---that
@ -1559,7 +1610,7 @@ by not storing keyboard events in strings. Here is how to do that:
@itemize @bullet
@item
Use vectors instead of strings for key sequences, when you plan to use
them for anything other than as arguments @code{lookup-key} and
them for anything other than as arguments to @code{lookup-key} and
@code{define-key}. For example, you can use
@code{read-key-sequence-vector} instead of @code{read-key-sequence}, and
@code{this-command-keys-vector} instead of @code{this-command-keys}.
@ -1776,8 +1827,8 @@ this Emacs session. This includes key sequences read from the terminal
and key sequences read from keyboard macros being executed.
@end defvar
@tindex num-nonmacro-input-events
@defvar num-nonmacro-input-events
@tindex num-nonmacro-input-events
This variable holds the total number of input events received so far
from the terminal---not counting those generated by keyboard macros.
@end defvar
@ -1803,6 +1854,12 @@ If @code{cursor-in-echo-area} is non-@code{nil}, then @code{read-event}
moves the cursor temporarily to the echo area, to the end of any message
displayed there. Otherwise @code{read-event} does not move the cursor.
If @code{read-event} gets an event is defined as a help character, in
some cases @code{read-event} processes the event directly without
returning. @xref{Help Functions}. Certain other events, called
@dfn{special events}, are also processed directly within
@code{read-event} (@pxref{Special Events}).
Here is what happens if you call @code{read-event} and then press the
right-arrow function key:
@ -2506,9 +2563,10 @@ the command to be considered complex.
@defvar command-history
This variable's value is a list of recent complex commands, each
represented as a form to evaluate. It continues to accumulate all
complex commands for the duration of the editing session, but all but
the first (most recent) thirty elements are deleted when a garbage
collection takes place (@pxref{Garbage Collection}).
complex commands for the duration of the editing session, but when it
reaches the maximum size (specified by the variable
@code{history-length}), the oldest elements are deleted as new ones are
added.
@example
@group

15
lispref/compile.texi
View file

@ -3,7 +3,7 @@
@c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/compile
@node Byte Compilation, Advising, Loading, Top
@node Byte Compilation, Advising Functions, Loading, Top
@chapter Byte Compilation
@cindex byte-code
@cindex compilation
@ -20,6 +20,12 @@ hardware (as true compiled code is), byte-code is completely
transportable from machine to machine without recompilation. It is not,
however, as fast as true compiled code.
Compiling a Lisp file with the Emacs byte compiler always reads the
file as multibyte text, even if Emacs was started with @samp{--unibyte},
unless the file specifies otherwise. This is so that compilation gives
results compatible with running the same file without compilation.
@xref{Loading Non-ASCII}.
In general, any version of Emacs can run byte-compiled code produced
by recent earlier versions of Emacs, but the reverse is not true. A
major incompatible change was introduced in Emacs version 19.29, and
@ -164,9 +170,10 @@ function.
@end deffn
@deffn Command byte-compile-file filename
This function compiles a file of Lisp code named @var{filename} into
a file of byte-code. The output file's name is made by appending
@samp{c} to the end of @var{filename}.
This function compiles a file of Lisp code named @var{filename} into a
file of byte-code. The output file's name is made by changing the
@samp{.el} suffix into @samp{.elc}; if @var{filename} does not end in
@samp{.el}, it adds @samp{.elc} to the end of @var{filename}.
Compilation works by reading the input file one form at a time. If it
is a definition of a function or macro, the compiled function or macro

12
lispref/control.texi
View file

@ -172,8 +172,8 @@ never evaluated---it is ignored. Thus, in the example below,
@end example
@end defspec
@tindex when
@defmac when condition then-forms@dots{}
@tindex when
This is a variant of @code{if} where there are no @var{else-forms},
and possibly several @var{then-forms}. In particular,
@ -189,8 +189,8 @@ is entirely equivalent to
@end example
@end defmac
@tindex condition
@defmac unless condition forms@dots{}
@tindex condition
This is a variant of @code{if} where there is no @var{then-form}:
@example
@ -550,10 +550,10 @@ have several ways of transferring control nonsequentially: @code{return},
@defspec catch tag body@dots{}
@cindex tag on run time stack
@code{catch} establishes a return point for the @code{throw} function. The
return point is distinguished from other such return points by @var{tag},
which may be any Lisp object. The argument @var{tag} is evaluated normally
before the return point is established.
@code{catch} establishes a return point for the @code{throw} function.
The return point is distinguished from other such return points by
@var{tag}, which may be any Lisp object except @code{nil}. The argument
@var{tag} is evaluated normally before the return point is established.
With the return point in effect, @code{catch} evaluates the forms of the
@var{body} in textual order. If the forms execute normally, without

79
lispref/customize.texi
View file

@ -31,6 +31,10 @@ The keyword @code{:tag} is an exception because any given item can only
display one name.
@table @code
@item :tag @var{name}
Use @var{name}, a string, instead of the item's name, to label the item
in customization menus and buffers.
@item :group @var{group}
Put this customization item in group @var{group}. When you use
@code{:group} in a @code{defgroup}, it makes the new group a subgroup of
@ -48,10 +52,6 @@ other documentation.
There are three alternatives you can use for @var{link-data}:
@table @code
@item :tag @var{name}
Use @var{name}, a string, instead of the item's name, to label the item
in customization menus and buffers.
@item (custom-manual @var{info-node})
Link to an Info node; @var{info-node} is a string which specifies the
node name, as in @code{"(emacs)Top"}. The link appears as
@ -109,23 +109,22 @@ keyword.
The way to declare new customization groups is with @code{defgroup}.
@tindex defgroup
@defmac defgroup group members doc [keyword value]...
@tindex defgroup
Declare @var{group} as a customization group containing @var{members}.
Do not quote the symbol @var{group}. The argument @var{doc} specifies
the documentation string for the group.
The arguments @var{members} can be an alist whose elements specify
customization items to be members of the group; however, normally
The argument @var{members} is a list specifying an initial set of
customization items to be members of the group. However, most often
@var{members} is @code{nil}, and you specify the group's members by
using the @code{:group} keyword when defining those members.
@ignore
@code{(@var{name} @var{widget})}. Here @var{name} is a symbol, and
@var{widget} is a widget for editing that symbol. Useful widgets are
@code{custom-variable} for editing variables, @code{custom-face} for
editing faces, and @code{custom-group} for editing groups.
@end ignore
If you want to specify group members through @var{members}, each element
should have the form @code{(@var{name} @var{widget})}. Here @var{name}
is a symbol, and @var{widget} is a widget type for editing that symbol.
Useful widgets are @code{custom-variable} for a variable,
@code{custom-face} for a face, and @code{custom-group} for a group.
In addition to the common keywords (@pxref{Common Keywords}), you can
use this keyword in @code{defgroup}:
@ -162,18 +161,18 @@ turn this feature back on, if someone would like to do the work.
Use @code{defcustom} to declare user-editable variables.
@tindex defcustom
@defmac defcustom option default doc [keyword value]...
@tindex defcustom
Declare @var{option} as a customizable user option variable. Do not
quote @var{option}. The argument @var{doc} specifies the documentation
string for the variable.
If @var{option} is void, @code{defcustom} initializes it to
@var{default}. @var{default} should be an expression to compute the
value; be careful in writing it, because it can be be evaluated on more
value; be careful in writing it, because it can be evaluated on more
than one occasion.
The following additional keywords are defined:
The following additional keywords are accepted:
@table @code
@item :type @var{type}
@ -191,8 +190,9 @@ elements of the hook value. The user is not restricted to using only
these functions, but they are offered as convenient alternatives.
@item :version @var{version}
This option specifies that the variable's default value was changed in
Emacs version @var{version}. For example,
This option specifies that the variable was first introduced, or its
default value was changed, in Emacs version @var{version}. The value
@var{version} must be a string. For example,
@example
(defcustom foo-max 34
@ -260,7 +260,7 @@ Keywords}. Here is an example, from the library @file{paren.el}:
(defcustom show-paren-mode nil
"Toggle Show Paren mode@enddots{}"
:set (lambda (symbol value)
(show-paren-mode (or value 0)))
(show-paren-mode (or value 0)))
:initialize 'custom-initialize-default
:type 'boolean
:group 'paren-showing
@ -369,6 +369,13 @@ completion with @kbd{M-@key{TAB}}.
The value must be a directory name, and you can do completion with
@kbd{M-@key{TAB}}.
@item hook
The value must be a list of functions (or a single function, but that is
obsolete usage). This customization type is used for hook variables.
You can use the @code{:option} in the @code{defcustom} for a hook
variable to specify functions recommended for use in the hook;
see @ref{Variable Definitions}.
@item symbol
The value must be a symbol. It appears in the customization buffer as
the name of the symbol.
@ -381,6 +388,10 @@ it is a function name, you can do completion with @kbd{M-@key{TAB}}.
The value must be a variable name, and you can do completion with
@kbd{M-@key{TAB}}.
@item face
The value must be a symbol which is a face name, and you can do
completion with @kbd{M-@key{TAB}}.
@item boolean
The value is boolean---either @code{nil} or @code{t}. Note that by
using @code{choice} and @code{const} together (see the next section),
@ -399,24 +410,26 @@ doing that:
@table @code
@item (restricted-sexp :match-alternatives @var{criteria})
The value may be any Lisp object that satisfies one of @var{criteria}.
@var{criteria} should be a list, and each elements should be
@var{criteria} should be a list, and each element should be
one of these possibilities:
@itemize @bullet
@item
A predicate---that is, a function of one argument that returns non-@code{nil}
if the argument fits a certain type. This means that objects of that type
are acceptable.
A predicate---that is, a function of one argument that has no side
effects, and returns either @code{nil} or non-@code{nil} according to
the argument. Using a predicate in the list says that objects for which
the predicate returns non-@code{nil} are acceptable.
@item
A quoted constant---that is, @code{'@var{object}}. This means that
@var{object} itself is an acceptable value.
A quoted constant---that is, @code{'@var{object}}. This sort of element
in the list says that @var{object} itself is an acceptable value.
@end itemize
For example,
@example
(restricted-sexp :match-alternatives (integerp 't 'nil))
(restricted-sexp :match-alternatives
(integerp 't 'nil))
@end example
@noindent
@ -427,7 +440,7 @@ syntax, and the user edits them textually.
@item (cons @var{car-type} @var{cdr-type})
The value must be a cons cell, its @sc{car} must fit @var{car-type}, and
its @sc{cdr} must fit @var{cdr-type}. For example, @code{(const string
its @sc{cdr} must fit @var{cdr-type}. For example, @code{(cons string
symbol)} is a customization type which matches values such as
@code{("foo" . foo)}.
@ -444,7 +457,7 @@ For example, @code{(list integer string function)} describes a list of
three elements; the first element must be an integer, the second a
string, and the third a function.
In the customization buffer, the each element is displayed and edited
In the customization buffer, each element is displayed and edited
separately, according to the type specified for it.
@item (vector @var{element-types}@dots{})
@ -466,10 +479,10 @@ including the @code{:tag} keyword in the alternatives. For example, if
an integer stands for a number of spaces, while a string is text to use
verbatim, you might write the customization type this way,
@smallexample
@example
(choice (integer :tag "Number of spaces")
(string :tag "Literal text"))
@end smallexample
@end example
@noindent
so that the menu offers @samp{Number of spaces} and @samp{Literal Text}.
@ -488,11 +501,11 @@ The main use of @code{const} is inside of @code{choice}. For example,
@code{:tag} is often used with @code{const}, inside of @code{choice}.
For example,
@smallexample
@example
(choice (const :tag "Yes" t)
(const :tag "No" nil)
(const :tag "Ask" foo))
@end smallexample
@end example
@item (function-item @var{function})
Like @code{const}, but used for values which are functions. This
@ -733,7 +746,7 @@ in the buffer with a positive tabbing order, or @code{nil}
@end enumerate
@item :parent
The parent of a nested widget (e.g. a @code{menu-choice} item or an
The parent of a nested widget (e.g., a @code{menu-choice} item or an
element of a @code{editable-list} widget).
@item :sibling-args

108
lispref/debugging.texi
View file

@ -3,7 +3,7 @@
@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1998 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/debugging
@node Debugging, Read and Print, Advising, Top
@node Debugging, Read and Print, Advising Functions, Top
@chapter Debugging Lisp Programs
There are three ways to investigate a problem in an Emacs Lisp program,
@ -12,8 +12,9 @@ depending on what you are doing with the program when the problem appears.
@itemize @bullet
@item
If the problem occurs when you run the program, you can use a Lisp
debugger (either the default debugger or Edebug) to investigate what is
happening during execution.
debugger to investigate what is happening during execution. In addition
to the ordinary debugger, Emacs comes with a source level debugger,
Edebug. This chapter describes both of them.
@item
If the problem is syntactic, so that Lisp cannot even read the program,
@ -26,9 +27,9 @@ compiler, you need to know how to examine the compiler's input buffer.
@menu
* Debugger:: How the Emacs Lisp debugger is implemented.
* Edebug:: A source-level Emacs Lisp debugger.
* Syntax Errors:: How to find syntax errors.
* Compilation Errors:: How to find errors that show up in byte compilation.
* Edebug:: A source-level Emacs Lisp debugger.
@end menu
Another useful debugging tool is the dribble file. When a dribble
@ -45,13 +46,13 @@ Afterward, you can examine the file to find out what input was used.
@cindex Lisp debugger
@cindex break
The @dfn{Lisp debugger} provides the ability to suspend evaluation of
a form. While evaluation is suspended (a state that is commonly known
as a @dfn{break}), you may examine the run time stack, examine the
values of local or global variables, or change those values. Since a
break is a recursive edit, all the usual editing facilities of Emacs are
available; you can even run programs that will enter the debugger
recursively. @xref{Recursive Editing}.
The ordinary @dfn{Lisp debugger} provides the ability to suspend
evaluation of a form. While evaluation is suspended (a state that is
commonly known as a @dfn{break}), you may examine the run time stack,
examine the values of local or global variables, or change those values.
Since a break is a recursive edit, all the usual editing facilities of
Emacs are available; you can even run programs that will enter the
debugger recursively. @xref{Recursive Editing}.
@menu
* Error Debugging:: Entering the debugger when an error happens.
@ -74,25 +75,28 @@ happens. This allows you to investigate the immediate causes of the
error.
However, entry to the debugger is not a normal consequence of an
error. Many commands frequently get Lisp errors when invoked in
inappropriate contexts (such as @kbd{C-f} at the end of the buffer) and
during ordinary editing it would be very unpleasant to enter the
debugger each time this happens. If you want errors to enter the
debugger, set the variable @code{debug-on-error} to non-@code{nil}.
error. Many commands frequently cause Lisp errors when invoked
inappropriately (such as @kbd{C-f} at the end of the buffer), and during
ordinary editing it would be very inconvenient to enter the debugger
each time this happens. So if you want errors to enter the debugger, set
the variable @code{debug-on-error} to non-@code{nil}. (The command
@code{toggle-debug-on-error} provides an easy way to do this.)
@defopt debug-on-error
This variable determines whether the debugger is called when an error is
signaled and not handled. If @code{debug-on-error} is @code{t}, all
errors call the debugger. If it is @code{nil}, none call the debugger.
kinds of errors call the debugger (except those listed in
@code{debug-ignored-errors}). If it is @code{nil}, none call the
debugger.
The value can also be a list of error conditions that should call the
debugger. For example, if you set it to the list
@code{(void-variable)}, then only errors about a variable that has no
value invoke the debugger.
When this variable is non-@code{nil}, Emacs does not catch errors that
happen in process filter functions and sentinels. Therefore, these
errors also can invoke the debugger. @xref{Processes}.
When this variable is non-@code{nil}, Emacs does not create an error
handler around process filter functions and sentinels. Therefore,
errors in these functions also invoke the debugger. @xref{Processes}.
@end defopt
@defopt debug-ignored-errors
@ -117,10 +121,10 @@ debugger, even if @code{debug-on-error} is non-@code{nil}. In other
words, @code{condition-case} gets a chance to handle the error before
the debugger gets a chance.
If you set @code{debug-on-signal} non-@code{nil}, then the debugger gets
first chance at every error; an error will invoke the debugger
regardless of any @code{condition-case}, if the fits the criterion
specified by the values of @code{debug-on-error} and
If you set @code{debug-on-signal} to a non-@code{nil} value, then the
debugger gets the first chance at every error; an error will invoke the
debugger regardless of any @code{condition-case}, if it fits the
criterion specified by the values of @code{debug-on-error} and
@code{debug-ignored-errors}.
@strong{Warning:} This variable is strong medicine! Various parts of
@ -134,13 +138,14 @@ enter the debugger.
@end defopt
To debug an error that happens during loading of the @file{.emacs}
file, use the option @samp{-debug-init}, which binds
@code{debug-on-error} to @code{t} while @file{.emacs} is loaded and
inhibits use of @code{condition-case} to catch init-file errors.
file, use the option @samp{--debug-init}, which binds
@code{debug-on-error} to @code{t} while @file{.emacs} is loaded, and
bypasses the @code{condition-case} which normally catches errors in the
init-file.
If your @file{.emacs} file sets @code{debug-on-error}, the effect may
not last past the end of loading @file{.emacs}. (This is an undesirable
byproduct of the code that implements the @samp{-debug-init} command
byproduct of the code that implements the @samp{--debug-init} command
line option.) The best way to make @file{.emacs} set
@code{debug-on-error} permanently is with @code{after-init-hook}, like
this:
@ -269,8 +274,9 @@ not currently set up to break on entry. It always returns
You can cause the debugger to be called at a certain point in your
program by writing the expression @code{(debug)} at that point. To do
this, visit the source file, insert the text @samp{(debug)} at the
proper place, and type @kbd{C-M-x}. Be sure to undo this insertion
before you save the file!
proper place, and type @kbd{C-M-x}. @strong{Warning:} if you do this
for temporary debugging purposes, be sure to undo this insertion before
you save the file!
The place where you insert @samp{(debug)} must be a place where an
additional form can be evaluated and its value ignored. (If the value
@ -339,8 +345,8 @@ same function. (To do this, visit the source for the function and type
@item c
Exit the debugger and continue execution. When continuing is possible,
it resumes execution of the program as if the debugger had never been
entered (aside from the effect of any variables or data structures you
may have changed while inside the debugger).
entered (aside from any side-effects that you caused by changing
variable values or data structures while inside the debugger).
Continuing is possible after entry to the debugger due to function entry
or exit, explicit invocation, or quitting. You cannot continue if the
@ -371,10 +377,10 @@ remove the star from the line in the backtrace buffer.
Read a Lisp expression in the minibuffer, evaluate it, and print the
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.
temporarily restores their values from outside the debugger, so you can
examine and change 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 R
Like @kbd{e}, but also save the result of evaluation in the
@ -404,7 +410,8 @@ You can't use @kbd{r} when the debugger was entered due to an error.
@node Invoking the Debugger
@subsection Invoking the Debugger
Here we describe fully the function used to invoke the debugger.
Here we describe in full detail the function @code{debug} that is used
to invoke the debugger.
@defun debug &rest debugger-args
This function enters the debugger. It switches buffers to a buffer
@ -418,18 +425,15 @@ then @code{debug} switches back to the previous buffer and returns to
whatever called @code{debug}. This is the only way the function
@code{debug} can return to its caller.
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
top of the @samp{*Backtrace*} buffer. This mechanism is used to display
a message to the user.
The use of the @var{debugger-args} is that @code{debug} displays the
rest of its arguments at the top of the @samp{*Backtrace*} buffer, so
that the user can see them. Except as described below, this is the
@emph{only} way these arguments are used.
However, if the first argument passed to @code{debug} is one of the
following special values, then it has special significance. Normally,
these values are passed to @code{debug} only by the internals of Emacs
and the debugger, and not by programmers calling @code{debug}.
The special values are:
However, certain values for first argument to @code{debug} have a
special significance. (Normally, these values are used only by the
internals of Emacs, and not by programmers calling @code{debug}.) Here
is a table of these special values:
@table @code
@item lambda
@ -640,6 +644,8 @@ If @var{frame-number} is out of range, @code{backtrace-frame} returns
@code{nil}.
@end defun
@include edebug.texi
@node Syntax Errors
@section Debugging Invalid Lisp Syntax
@ -658,7 +664,9 @@ if it goes to the place where that defun appears to end. If it does
not, there is a problem in that defun.
However, unmatched parentheses are the most common syntax errors in
Lisp, and we can give further advice for those cases.
Lisp, and we can give further advice for those cases. (In addition,
just moving point through the code with Show Paren mode enabled might
find the mismatch.)
@menu
* Excess Open:: How to find a spurious open paren or missing close.
@ -753,5 +761,3 @@ the error.
successfully, then point is located at the end of the form. In this
case, this technique can't localize the error precisely, but can still
show you which function to check.
@include edebug.texi

125
lispref/display.texi
View file

@ -167,6 +167,9 @@ If it is non-@code{nil}, these lines are truncated; otherwise,
@code{truncate-lines} says what to do with them.
@end defopt
When horizontal scrolling (@pxref{Horizontal Scrolling}) is in use in
a window, that forces truncation.
You can override the glyphs that indicate continuation or truncation
using the display table; see @ref{Display Tables}.
@ -236,8 +239,8 @@ Minibuffer depth is 0.
@end example
@end defun
@tindex current-message
@defun current-message
@tindex current-message
This function returns the message currently being displayed in the
echo area, or @code{nil} if there is none.
@end defun
@ -252,8 +255,8 @@ The value is normally @code{nil}; Lisp programs bind it to @code{t}
for brief periods of time.
@end defvar
@tindex echo-area-clear-hook
@defvar echo-area-clear-hook
@tindex echo-area-clear-hook
This normal hook is run whenever the echo area is cleared---either by
@code{(message nil)} or for any other reason.
@end defvar
@ -278,8 +281,9 @@ 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.
continuing, the prefix key is echoed in the echo area. (Once echoing
begins in a key sequence, all subsequent characters in the same key
sequence are echoed immediately.)
If the value is zero, then command input is not echoed.
@end defvar
@ -290,7 +294,8 @@ If the value is zero, then command input is not echoed.
@cindex invisible text
You can make characters @dfn{invisible}, so that they do not appear on
the screen, with the @code{invisible} property. This can be either a
text property or a property of an overlay.
text property (@pxref{Text Properties}) or a property of an overlay
(@pxref{Overlays}).
In the simplest case, any non-@code{nil} @code{invisible} property makes
a character invisible. This is the default case---if you don't alter
@ -342,14 +347,14 @@ by a visible newline, it displays an ellipsis.
Two functions are specifically provided for adding elements to
@code{buffer-invisibility-spec} and removing elements from it.
@tindex add-to-invisibility-spec
@defun add-to-invisibility-spec element
@tindex add-to-invisibility-spec
Add the element @var{element} to @code{buffer-invisibility-spec}
(if it is not already present in that list).
@end defun
@tindex remove-from-invisibility-spec
@defun remove-from-invisibility-spec element
@tindex remove-from-invisibility-spec
Remove the element @var{element} from @code{buffer-invisibility-spec}.
@end defun
@ -393,8 +398,8 @@ temporarily modifying their invisible and intangible properties. If you
want this to be done differently for a certain overlays, give it a
@code{isearch-open-invisible-temporary} property which is a function.
The function is called with two arguments: the first is the overlay, and
the second is @code{nil} to make the overlay visible or @code{t} to make
it invisible again.
the second is @code{t} to make the overlay visible, or @code{nil} to
make it invisible again.
@node Selective Display
@section Selective Display
@ -598,6 +603,17 @@ The value of the last form in @var{forms} is returned.
If this variable is non-@code{nil}, @code{with-output-to-temp-buffer}
calls it as a function to do the job of displaying a help buffer. The
function gets one argument, which is the buffer it should display.
It is a good idea for this function to run @code{temp-buffer-show-hook}
just as @code{with-output-to-temp-buffer} normally would, inside of
@code{save-window-excursion} and with the chosen window and buffer
selected.
@end defvar
@defvar temp-buffer-show-hook
This normal hook is run by @code{with-output-to-temp-buffer} after
displaying the help buffer. When the hook runs, the help buffer is
current, and the window it was displayed in is selected.
@end defvar
@defun momentary-string-display string position &optional char message
@ -675,15 +691,16 @@ these affect the display of the text within the overlay.
@node Overlay Properties
@subsection Overlay Properties
Overlay properties are like text properties in some respects, but the
differences are more important than the similarities. Text properties
are considered a part of the text; overlays are specifically considered
not to be part of the text. Thus, copying text between various buffers
and strings preserves text properties, but does not try to preserve
overlays. Changing a buffer's text properties marks the buffer as
modified, while moving an overlay or changing its properties does not.
Unlike text property changes, overlay changes are not recorded in the
buffer's undo list.
Overlay properties are like text properties in that the properties that
alter how a character is displayed can come from either source. But in
most respects they are different. Text properties are considered a part
of the text; overlays are specifically considered not to be part of the
text. Thus, copying text between various buffers and strings preserves
text properties, but does not try to preserve overlays. Changing a
buffer's text properties marks the buffer as modified, while moving an
overlay or changing its properties does not. Unlike text property
changes, overlay changes are not recorded in the buffer's undo list.
@xref{Text Properties}, for comparison.
@table @code
@item priority
@ -773,11 +790,14 @@ The @code{intangible} property on an overlay works just like the
@code{intangible} text property. @xref{Special Properties}, for details.
@item isearch-open-invisible
@itemx isearch-open-invisible-temporary
These properties control how incremental search should make invisible an
overlay visible, either permanently or temporarily. @xref{Invisible
This property tells incremental search how to make an invisible overlay
visible, permanently, if the final match overlaps it. @xref{Invisible
Text}.
@item isearch-open-invisible-temporary
This property tells incremental search how to make an invisible overlay
visible, temporarily, during the search. @xref{Invisible Text}.
@item before-string
@kindex before-string @r{(overlay property)}
This property's value is a string to add to the display at the beginning
@ -861,8 +881,11 @@ This function returns the buffer that @var{overlay} belongs to.
@defun delete-overlay overlay
This function deletes @var{overlay}. The overlay continues to exist as
a Lisp object, but ceases to be part of the buffer it belonged to, and
ceases to have any effect on display.
a Lisp object, but ceases to be attached to the buffer it belonged to,
and ceases to have any effect on display.
A deleted overlay is not permanently useless. You can give it
a new buffer position by calling @code{move-overlay}.
@end defun
@defun move-overlay overlay start end &optional buffer
@ -886,8 +909,8 @@ An overlay contains position @var{pos} if it begins at or before
@var{pos}, and ends after @var{pos}.
@end defun
@tindex overlays-in
@defun overlays-in beg end
@tindex overlays-in
This function returns a list of the overlays that overlap the region
@var{beg} through @var{end}. ``Overlap'' means that at least one
character is contained within the overlay and also contained within the
@ -912,20 +935,20 @@ Since not all characters have the same width, these functions let you
check the width of a character. @xref{Primitive Indent}, and
@ref{Screen Lines}, for related functions.
@tindex char-width
@defun char-width char
@tindex char-width
This function returns the width in columns of the character @var{char},
if it were displayed in the current buffer and the selected window.
@end defun
@tindex string-width
@defun string-width string
@tindex string-width
This function returns the width in columns of the string @var{string},
if it were displayed in the current buffer and the selected window.
@end defun
@tindex truncate-string-to-width
@defun truncate-string-to-width string width &optional start-column padding
@tindex truncate-string-to-width
This function returns the part of @var{string} that fits within
@var{width} columns, as a new string.
@ -1033,22 +1056,22 @@ one.
@end table
@node Defining Faces
@section Defining Faces
@subsection Defining Faces
The way to define a new face is with @code{defface}. This creates a
kind of customization item (@pxref{Customization}) which the user can
customize using the Customization buffer (@pxref{Easy Customization,,,
emacs, The GNU Emacs Manual}).
@tindex defface
@defmac defface face spec doc [keyword value]...
@tindex defface
Declare @var{face} as a customizable face that defaults according to
@var{spec}. Do not quote the symbol @var{face}. The argument @var{doc}
specifies the face documentation.
When @code{defface} executes, it defines the face according to
@var{spec}, then uses any customizations saved in the @file{.emacs} file
to override that specification.
@var{spec}, then uses any customizations that were read from the
@file{.emacs} file to override that specification.
The purpose of @var{spec} is to specify how the face should appear on
different kinds of terminals. It should be an alist whose elements have
@ -1069,7 +1092,7 @@ This element of @var{spec} matches all frames. Therefore, any
subsequent elements of @var{spec} are never used. Normally
@code{t} is used in the last (or only) element of @var{spec}.
@item an list
@item a list
If @var{display} is alist, each elements should have the form
@code{(@var{characteristic} @var{value}@dots{})}. Here
@var{characteristic} specifies a way of classifying frames, and the
@ -1222,19 +1245,20 @@ they are used automatically to handle certain shades of gray.
@defun set-face-font face font &optional frame
This function sets the font of face @var{face}. The argument @var{font}
should be a string. Note that if you set the font explicitly, the bold
and italic attributes cease to have any effect, because the precise font
that you specified is always used.
should be a string, either a valid font name for your system or the name
of an Emacs fontset (@pxref{Fontsets}). Note that if you set the font
explicitly, the bold and italic attributes cease to have any effect,
because the precise font that you specified is always used.
@end defun
@tindex set-face-bold-p
@defun set-face-bold-p face bold-p &optional frame
@tindex set-face-bold-p
This function sets the bold attribute of face @var{face}.
Non-@code{nil} means bold; @code{nil} means non-bold.
@end defun
@tindex set-face-italic-p
@defun set-face-italic-p face italic-p &optional frame
@tindex set-face-italic-p
This function sets the italic attribute of face @var{face}.
Non-@code{nil} means italic; @code{nil} means non-italic.
@end defun
@ -1269,13 +1293,13 @@ This function returns the name of the background stipple pattern of face
This function returns the name of the font of face @var{face}.
@end defun
@tindex face-bold-p
@defun face-bold-p face &optional frame
@tindex face-bold-p
This function returns the bold attribute of face @var{face}.
@end defun
@tindex face-italic-p
@defun face-italic-p face &optional frame
@tindex face-italic-p
This function returns the italic attribute of face @var{face}.
@end defun
@ -1287,8 +1311,8 @@ This function returns the underline attribute of face @var{face}.
This function returns the face number of face @var{face}.
@end defun
@tindex face-documentation
@defun face-documentation face
@tindex face-documentation
This function returns the documentation string of face @var{face}, or
@code{nil} if none was specified for it.
@end defun
@ -1428,7 +1452,7 @@ just like the codes in the range 128 to 255.
@item
Character codes 128 through 255 map to sequences of four glyphs, where
the first glyph is the @sc{ASCII} code for @samp{\}, and the others are
digit characters representing the charatcer code in octal. (A display
digit characters representing the character code in octal. (A display
table can specify a glyph to use instead of @samp{\}.)
@item
@ -1497,7 +1521,8 @@ force redisplay of the mode line using a new display table, call
@node Display Table Format
@subsection Display Table Format
A display table is actually char-table with subtype @code{display-table}.
A display table is actually a char-table (@pxref{Char-Tables}) with
@code{display-table} as its subtype.
@defun make-display-table
This creates and returns a display table. The table initially has
@ -1550,8 +1575,8 @@ effect of setting @code{ctl-arrow} to a non-@code{nil} value:
(aset disptab 127 (vector ?^ ??)))
@end example
@tindex display-table-slot
@defun display-table-slot display-table slot
@tindex display-table-slot
This function returns the value of the extra slot @var{slot} of
@var{display-table}. The argument @var{slot} may be a number from 0 to
5 inclusive, or a slot name (symbol). Valid symbols are
@ -1559,8 +1584,8 @@ This function returns the value of the extra slot @var{slot} of
@code{selective-display}, and @code{vertical-border}.
@end defun
@tindex set-display-table-slot
@defun set-display-table-slot display-table slot value
@tindex set-display-table-slot
This function stores @var{value} in the extra slot @var{slot} of
@var{display-table}. The argument @var{slot} may be a number from 0 to
5 inclusive, or a slot name (symbol). Valid symbols are
@ -1669,14 +1694,14 @@ often you do this; frequent bells can become irritating. Also be
careful not to use just beeping when signaling an error is more
appropriate. (@xref{Errors}.)
@defun ding &optional dont-terminate
@defun ding &optional do-not-terminate
@cindex keyboard macro termination
This function beeps, or flashes the screen (see @code{visible-bell} below).
It also terminates any keyboard macro currently executing unless
@var{dont-terminate} is non-@code{nil}.
@var{do-not-terminate} is non-@code{nil}.
@end defun
@defun beep &optional dont-terminate
@defun beep &optional do-not-terminate
This is a synonym for @code{ding}.
@end defun
@ -1688,10 +1713,10 @@ provided the terminal's Termcap entry defines the visible bell
capability (@samp{vb}).
@end defvar
@tindex ring-bell-function
@defvar ring-bell-function
@tindex ring-bell-function
If this is non-@code{nil}, it specifies how Emacs should ``ring the
bell.'' Its value should bea function of no arguments.
bell.'' Its value should be a function of no arguments.
@end defvar
@node Window Systems
@ -1714,7 +1739,7 @@ terminal).
This variable is a normal hook which Emacs runs after handling the
initialization files. Emacs runs this hook after it has completed
loading your @file{.emacs} file, the default initialization file (if
any), and the terminal-specific Lisp code, and runring the hook
any), and the terminal-specific Lisp code, and running the hook
@code{term-setup-hook}.
This hook is used for internal purposes: setting up communication with

123
lispref/edebug.texi
View file

@ -36,7 +36,7 @@ Display expression results and evaluate expressions as if outside of
Edebug.
@item
Automatically reevaluate a list of expressions and
Automatically re-evaluate a list of expressions and
display their results each time Edebug updates the display.
@item
@ -199,11 +199,11 @@ steps into the call after instrumenting the function.
@cindex Common Lisp (Edebug)
@pindex cl.el @r{(Edebug)}
@pindex cl-specs.el
Edebug knows how to instrument all the standard special forms, an
interactive form with an expression argument, anonymous lambda
Edebug knows how to instrument all the standard special forms,
@code{interactive} forms with an expression argument, anonymous lambda
expressions, and other defining forms. Edebug cannot know what a
user-defined macro will do with the arguments of a macro call, so you
must tell it; @xref{Instrumenting Macro Calls}, for details.
must tell it; see @ref{Instrumenting Macro Calls}, for details.
When Edebug is about to instrument code for the first time in a
session, it runs the hook @code{edebug-setup-hook}, then sets it to
@ -212,7 +212,7 @@ session, it runs the hook @code{edebug-setup-hook}, then sets it to
using, but actually load them only if you use Edebug.
@findex eval-expression @r{(Edebug)}
To remove instrumentation from a definition, simply reevaluate its
To remove instrumentation from a definition, simply re-evaluate its
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}
@ -335,8 +335,8 @@ Step into the function or macro called by the form after point.
@end table
The @kbd{h} command proceeds to the stop point near the current location
if point, using a temporary breakpoint. See @ref{Breakpoints}, for more
about breakpoints.
of point, using a temporary breakpoint. See @ref{Breakpoints}, for more
information about breakpoints.
The @kbd{f} command runs the program forward over one expression. More
precisely, it sets a temporary breakpoint at the position that
@ -463,7 +463,7 @@ with @kbd{u}. First move point to the Edebug stop point of your choice,
then type @kbd{b} or @kbd{u} to set or unset a breakpoint there.
Unsetting a breakpoint where none has been set has no effect.
Reevaluating or reinstrumenting a definition forgets all its breakpoints.
Re-evaluating or reinstrumenting a definition forgets all its breakpoints.
A @dfn{conditional breakpoint} tests a condition each time the program
gets there. Any errors that occur as a result of evaluating the
@ -568,7 +568,7 @@ are bound to the values they had outside of Edebug.
@subsection Edebug Views
These Edebug commands let you view aspects of the buffer and window
status that obtained before entry to Edebug. The outside window
status as they were before entry to Edebug. The outside window
configuration is the collection of windows and contents that were in
effect outside of Edebug.
@ -745,7 +745,6 @@ After selecting @samp{*edebug*}, you can return to the source code
buffer with @kbd{C-c C-w}. The @samp{*edebug*} buffer is killed when
you continue execution, and recreated next time it is needed.
@node Printing in Edebug
@subsection Printing in Edebug
@ -765,7 +764,6 @@ and @code{edebug-print-level} specify the values to use within Edebug.)
@defopt edebug-print-length
If non-@code{nil}, bind @code{print-length} to this while printing
results in Edebug. The default value is @code{50}.
@xref{Printing in Edebug}.
@end defopt
@defopt edebug-print-level
@ -785,13 +783,13 @@ edebug-uninstall-custom-print}.
@example
(setq a '(x y))
(setcar a a))
(setcar a a)
@end example
@noindent
Custom printing prints this as @samp{Result: #1=(#1# y)}. The
@samp{#1=} notation labels the structure that follows it with the label
@samp{1}, and the @samp{#1#} notation references the previously labelled
@samp{1}, and the @samp{#1#} notation references the previously labeled
structure. This notation is used for any shared elements of lists or
vectors.
@ -857,12 +855,19 @@ last lines inserted.
@cindex frequency counts
@cindex performance analysis
Edebug provides rudimentary coverage testing and display of execution
frequency. All execution of an instrumented function accumulates
frequency counts, both before and after evaluation of each instrumented
expression, even if the execution mode is Go-nonstop. Coverage testing
is more expensive, so it is done only if @code{edebug-test-coverage} is
non-@code{nil}. The command @kbd{M-x edebug-display-freq-count}
displays both the frequency data and the coverage data (if recorded).
frequency. Coverage testing works by comparing the result of each
expression with the previous result; coverage is considered OK if two
different results are found. Thus, to sufficiently test the coverage of
your code, try to execute it under conditions that evaluate all
expressions more than once, and produce different results for each
expression. Coverage testing makes execution slower, so it is only done
if @code{edebug-test-coverage} is non-@code{nil}. Whether or not
coverage testing is enabled, frequency counting is performed for all
execution of an instrumented function, even if the execution mode is
Go-nonstop.
Use @kbd{M-x edebug-display-freq-count} to display both the
coverage information and the frequency counts for a definition.
@deffn Command edebug-display-freq-count
This command displays the frequency count data for each line of the
@ -871,15 +876,16 @@ current definition.
The frequency counts appear as comment lines after each line of code,
and you can undo all insertions with one @code{undo} command. The
counts appear under the @samp{(} before an expression or the @samp{)}
after an expression, or on the last character of a symbol. Values do
not appear if they are equal to the previous count on the same line.
after an expression, or on the last character of a variable. To
simplify the display, a count is not shown if it is equal to the
count of an earlier expression on the same line.
The character @samp{=} following the count for an expression says that
the expression has returned the same value each time it was evaluated
the expression has returned the same value each time it was evaluated.
This is the only coverage information that Edebug records.
To clear the frequency count and coverage data for a definition,
reinstrument it.
simply reinstrument it with @code{eval-defun}.
@end deffn
For example, after evaluating @code{(fac 5)} with a source
@ -930,8 +936,8 @@ program.
@itemize @bullet
@item
@code{max-lisp-eval-depth} and @code{max-specpdl-size} are both
incremented one time to reduce Edebug's impact on the stack.
You could, however, still run out of stack space when using Edebug.
incremented once to reduce Edebug's impact on the stack. You could,
however, still run out of stack space when using Edebug.
@item
The state of keyboard macro execution is saved and restored. While
@ -1067,8 +1073,8 @@ name.
@end deffn
Here is a simple example that defines the specification for the
@code{for} macro described in the Emacs Lisp Reference Manual, followed
by an alternative, equivalent specification.
@code{for} example macro (@code{Argument Evaluation}), followed by an
alternative, equivalent specification.
@example
(def-edebug-spec for
@ -1091,7 +1097,7 @@ None of the arguments is instrumented.
@item a symbol
The symbol must have an Edebug specification which is used instead.
This indirection is repeated until another kind of specification is
found. This allows you to inherit the specification for another macro.
found. This allows you to inherit the specification from another macro.
@item a list
The elements of the list describe the types of the arguments of a
@ -1137,9 +1143,8 @@ their meanings:
@table @code
@item sexp
A single Lisp object, not unevaluated.
@c "unevaluated expression" is not meaningful, because
@c an expression is a Lisp object intended for evaluation.
A single unevaluated expression, which is not instrumented.
@c an "expression" is not necessarily intended for evaluation.
@item form
A single evaluated expression, which is instrumented.
@ -1202,7 +1207,7 @@ succeeds.
@item &define
@kindex &define @r{(Edebug)}
Indicates that the specification is for a defining form. The defining
form itself is not instrumented (i.e. Edebug does not stop before and
form itself is not instrumented (that is, Edebug does not stop before and
after the defining form), but forms inside it typically will be
instrumented. The @code{&define} keyword should be the first element in
a list specification.
@ -1260,7 +1265,7 @@ a list whose elements match the specification @var{elements}.
A sublist specification may be a dotted list and the corresponding list
argument may then be a dotted list. Alternatively, the last @sc{cdr} of a
dotted list specification may be another sublist specification (via a
grouping or an indirect specification, e.g. @code{(spec . [(more
grouping or an indirect specification, e.g., @code{(spec . [(more
specs@dots{})])}) whose elements match the non-dotted list arguments.
This is useful in recursive specifications such as in the backquote
example below. Also see the description of a @code{nil} specification
@ -1293,7 +1298,7 @@ than once.
@item arg
The argument, a symbol, is the name of an argument of the defining form.
However, lambda list keywords (symbols starting with @samp{@code{&}})
However, lambda-list keywords (symbols starting with @samp{&})
are not allowed.
@item lambda-list
@ -1326,33 +1331,35 @@ necessarily mean a syntax error will be signaled; instead,
exhausted. Eventually every element of the argument list must be
matched by some element in the specification, and every required element
in the specification must match some argument.
When a syntax error is detected, it might not be reported until much
later after higher-level alternatives have been exhausted, and with the
point positioned further from the real error. But if backtracking is
disabled when an error occurs, it can be reported immediately. Note
that backtracking is also reenabled automatically in several situations;
it is reenabled when a new alternative is established by
@code{&optional}, @code{&rest}, or @code{&or}, or at the start of
processing a sublist, group, or indirect specification. The effect of
enabling or disabling backtracking is limited to the remainder of the
level currently being processed and lower levels.
Backtracking is disabled for the remainder of a sublist or group when
certain conditions occur, described below. Backtracking is reenabled
when a new alternative is established by @code{&optional}, @code{&rest},
or @code{&or}. It is also reenabled initially when processing a
sublist or group specification or an indirect specification.
You might want to disable backtracking to commit to some alternative so
that Edebug can provide a more specific syntax error message. Normally,
if no alternative matches, Edebug reports that none matched, but if one
alternative is committed to, Edebug can report how it failed to match.
First, backtracking is disabled while matching any of the form
specifications (i.e. @code{form}, @code{body}, @code{def-form}, and
Backtracking is disabled while matching any of the
form specifications (that is, @code{form}, @code{body}, @code{def-form}, and
@code{def-body}). These specifications will match any form so any error
must be in the form itself rather than at a higher level.
Second, backtracking is disabled after successfully matching a quoted
Backtracking is also disabled after successfully matching a quoted
symbol or string specification, since this usually indicates a
recognized construct. If you have a set of alternative constructs that
recognized construct. But if you have a set of alternative constructs that
all begin with the same symbol, you can usually work around this
constraint by factoring the symbol out of the alternatives, e.g.,
@code{["foo" &or [first case] [second case] ...]}.
Third, backtracking may be explicitly disabled by using the
@code{gate} specification. This is useful when you know that
no higher alternatives may apply.
Most needs are satisfied by these two ways that bactracking is
automatically disabled, but occasionally it is useful to explicitly
disable backtracking by using the @code{gate} specification. This is
useful when you know that no higher alternatives could apply. See the
example of the @code{let} specification.
@node Specification Examples
@subsubsection Specification Examples
@ -1362,7 +1369,7 @@ the examples provided here.
A @code{let} special form has a sequence of bindings and a body. Each
of the bindings is either a symbol or a sublist with a symbol and
optional value. In the specification below, notice the @code{gate}
optional expression. In the specification below, notice the @code{gate}
inside of the sublist to prevent backtracking once a sublist is found.
@example
@ -1491,19 +1498,11 @@ function entry or exit per line, indented by the recursion level.
The default value is @code{nil}.
Also see @code{edebug-tracing}, in @xref{Trace Buffer}.
Also see @code{edebug-tracing}, in @ref{Trace Buffer}.
@end defopt
@defopt edebug-test-coverage
If non-@code{nil}, Edebug tests coverage of all expressions debugged.
This is done by comparing the result of each expression
with the previous result. Coverage is considered OK if two different
results are found. So to sufficiently test the coverage of your code,
try to execute it under conditions that evaluate all expressions more
than once, and produce different results for each expression.
Use @kbd{M-x edebug-display-freq-count} to display the frequency count
and coverage information for a definition.
@xref{Coverage Testing}.
@end defopt

23
lispref/elisp.texi
View file

@ -4,6 +4,8 @@
@settitle GNU Emacs Lisp Reference Manual
@c %**end of header
@smallbook
@ifinfo
This version is the edition 2.5 of the GNU Emacs Lisp
Reference Manual. It corresponds to Emacs Version 20.3
@ -269,7 +271,7 @@ Editing Types
* Process Type:: A process running on the underlying OS.
* Stream Type:: Receive or send characters.
* Keymap Type:: What function a keystroke invokes.
* Syntax Table Type:: What a character means.
* Overlay Type:: How an overlay is represented.
Numbers
@ -291,7 +293,7 @@ Strings and Characters
* Text Comparison:: Comparing characters or strings.
* String Conversion:: Converting characters or strings and vice versa.
* Formatting Strings:: @code{format}: Emacs's analog of @code{printf}.
* Character Case:: Case conversion functions.
* Case Conversion:: Case conversion functions.
Lists
@ -443,6 +445,19 @@ Byte Compilation
* Compilation Functions:: Byte compilation functions.
* Disassembly:: Disassembling byte-code; how to read byte-code.
Advising Functions
* Simple Advice:: A simple example to explain the basics of advice.
* Defining Advice:: Detailed description of @code{defadvice}.
* Computed Advice:: ...is to @code{defadvice} as @code{fset} is to @code{defun}.
* Activation of Advice:: Advice doesn't do anything until you activate it.
* Enabling Advice:: You can enable or disable each piece of advice.
* Preactivation:: Preactivation is a way of speeding up the
loading of compiled advice.
* Argument Access:: How advice can access the function's arguments.
* Subr Arguments:: Accessing arguments when advising a primitive.
* Combined Definition:: How advice is implemented.
Debugging Lisp Programs
* Debugger:: How the Emacs Lisp debugger is implemented.
@ -684,7 +699,7 @@ Frames
* 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.
* Window System 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.
@ -951,7 +966,7 @@ Object Internals
@include index.texi
@node New Symbols, , Index, Top
@chapter New Symbols Since the Previous Edition
@unnumbered New Symbols Since the Previous Edition
@printindex tp

2
lispref/errors.texi
View file

@ -104,7 +104,7 @@ This is a @code{file-error}.@*
@xref{Regular Expressions}.
@item mark-inactive
@code{Mark inactive"}@*
@code{"Mark inactive"}@*
@xref{The Mark}.
@item no-catch

7
lispref/eval.texi
View file

@ -464,6 +464,9 @@ Emacs Lisp with a reference to where each is described.
@item quote
@pxref{Quoting}
@item save-current-buffer
@pxref{Current Buffer}
@item save-excursion
@pxref{Excursions}
@ -657,8 +660,10 @@ The depth limit counts internal uses of @code{eval}, @code{apply}, and
expressions, and recursive evaluation of function call arguments and
function body forms, as well as explicit calls in Lisp code.
The default value of this variable is 200. If you set it to a value
The default value of this variable is 300. If you set it to a value
less than 100, Lisp will reset it to 100 if the given value is reached.
Entry to the Lisp debugger increases the value, if there is little room
left, to make sure the debugger itself has room to execute.
@code{max-specpdl-size} provides another limit on nesting.
@xref{Local Variables}.

141
lispref/files.texi
View file

@ -15,7 +15,7 @@ described in @ref{Backups and Auto-Saving}.
Many of the file functions take one or more arguments that are file
names. A file name is actually a string. Most of these functions
expand file name arguments using @code{expand-file-name}, so that
expand file name arguments by calling @code{expand-file-name}, so that
@file{~} is handled correctly, as are relative file names (including
@samp{../}). These functions don't recognize environment variable
substitutions such as @samp{$HOME}. @xref{File Name Expansion}.
@ -201,9 +201,9 @@ used, and in many cases only some of the functions are called.
@comment node-name, next, previous, up
@subsection Subroutines of Visiting
The @code{find-file-noselect} function uses the
@code{create-file-buffer} and @code{after-find-file} functions as
subroutines. Sometimes it is useful to call them directly.
The @code{find-file-noselect} function uses two important subroutines
which are sometimes useful in user Lisp code: @code{create-file-buffer}
and @code{after-find-file}. This section explains how to use them.
@defun create-file-buffer filename
This function creates a suitably named buffer for visiting
@ -251,7 +251,7 @@ If @var{warn} is non-@code{nil}, then this function issues a warning
if an auto-save file exists and is more recent than the visited file.
The last thing @code{after-find-file} does is call all the functions
in @code{find-file-hooks}.
in the list @code{find-file-hooks}.
@end defun
@node Saving Buffers
@ -334,6 +334,12 @@ You might wish to save the file modes value returned by
@code{backup-buffer} and use that to set the mode bits of the file that
you write. This is what @code{save-buffer} normally does.
The hook functions in @code{write-file-hooks} are also responsible for
encoding the data (if desired): they must choose a suitable coding
system (@pxref{Lisp and Coding Systems}), perform the encoding
(@pxref{Explicit Encoding}), and set @code{last-coding-system-used} to
the coding system that was used (@pxref{Specifying Coding Systems}).
Do not make this variable buffer-local. To set up buffer-specific hook
functions, use @code{write-contents-hooks} instead.
@ -448,12 +454,13 @@ 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.
It works to read a special file with @code{insert-file-contents}
as long as @var{replace} and @var{visit} are @code{nil}.
It is possible to read a special file (such as a FIFO or an I/O device)
with @code{insert-file-contents}, as long as @var{replace} and
@var{visit} are @code{nil}.
@end defun
@tindex insert-file-contents-literally
@defun insert-file-contents-literally filename &optional visit beg end replace
@tindex insert-file-contents-literally
This function works like @code{insert-file-contents} except that it does
not do format decoding (@pxref{Format Conversion}), does not do
character code conversion (@pxref{Coding Systems}), does not run
@ -485,7 +492,7 @@ An error is signaled if @var{filename} specifies a nonwritable file,
or a nonexistent file in a directory where files cannot be created.
@end deffn
@deffn Command write-region start end filename &optional append visit
@deffn Command write-region start end filename &optional append visit confirm
This function writes the region delimited by @var{start} and @var{end}
in the current buffer into the file specified by @var{filename}.
@ -496,6 +503,9 @@ that string, rather than text from the buffer.
If @var{append} is non-@code{nil}, then the specified text is appended
to the existing file contents (if any).
If @var{confirm} is non-@code{nil}, then @code{write-region} asks
for confirmation if @var{filename} names an existing file.
If @var{visit} is @code{t}, then Emacs establishes an association
between the buffer and the file: the buffer is then visiting that file.
It also sets the last file modification time for the current buffer to
@ -524,8 +534,8 @@ feature is useful for programs that use files for internal purposes,
files that the user does not need to know about.
@end deffn
@tindex with-temp-file
@defmac with-temp-file file body...
@tindex with-temp-file
The @code{with-temp-file} macro evaluates the @var{body} forms with a
temporary buffer as the current buffer; then, at the end, it writes the
buffer contents into file @var{file}. It kills the temporary buffer
@ -732,8 +742,8 @@ we can deduce that any attempt to read a file in @file{/foo/} will
give an error.
@end defun
@tindex access-file
@defun access-file filename string
@tindex access-file
This function opens file @var{filename} for reading, then closes it and
returns @code{nil}. However, if the open fails, it signals an error
using @var{string} as the error message text.
@ -1103,9 +1113,9 @@ In the first part of the following example, we list two files,
@example
@group
% ls -l fo*
-rw-rw-rw- 1 rms 29 Aug 18 20:32 foo
-rw-rw-rw- 1 rms 24 Aug 18 20:31 foo3
% ls -li fo*
81908 -rw-rw-rw- 1 rms 29 Aug 18 20:32 foo
84302 -rw-rw-rw- 1 rms 24 Aug 18 20:31 foo3
@end group
@end example
@ -1115,23 +1125,22 @@ the files again. This shows two names for one file, @file{foo} and
@example
@group
(add-name-to-file "~/lewis/foo" "~/lewis/foo2")
(add-name-to-file "foo" "foo2")
@result{} nil
@end group
@group
% ls -l fo*
-rw-rw-rw- 2 rms 29 Aug 18 20:32 foo
-rw-rw-rw- 2 rms 29 Aug 18 20:32 foo2
-rw-rw-rw- 1 rms 24 Aug 18 20:31 foo3
% ls -li fo*
81908 -rw-rw-rw- 2 rms 29 Aug 18 20:32 foo
81908 -rw-rw-rw- 2 rms 29 Aug 18 20:32 foo2
84302 -rw-rw-rw- 1 rms 24 Aug 18 20:31 foo3
@end group
@end example
@c !!! Check whether this set of examples is consistent. --rjc 15mar92
Finally, we evaluate the following:
Finally, we evaluate the following:
@example
(add-name-to-file "~/lewis/foo" "~/lewis/foo3" t)
(add-name-to-file "foo" "foo3" t)
@end example
@noindent
@ -1141,22 +1150,22 @@ contents of @file{foo3} are lost.
@example
@group
(add-name-to-file "~/lewis/foo1" "~/lewis/foo3")
(add-name-to-file "foo1" "foo3")
@result{} nil
@end group
@group
% ls -l fo*
-rw-rw-rw- 3 rms 29 Aug 18 20:32 foo
-rw-rw-rw- 3 rms 29 Aug 18 20:32 foo2
-rw-rw-rw- 3 rms 29 Aug 18 20:32 foo3
% ls -li fo*
81908 -rw-rw-rw- 3 rms 29 Aug 18 20:32 foo
81908 -rw-rw-rw- 3 rms 29 Aug 18 20:32 foo2
81908 -rw-rw-rw- 3 rms 29 Aug 18 20:32 foo3
@end group
@end example
This function is meaningless on VMS, where multiple names for one file
are not allowed.
This function is meaningless on operating systems where multiple names
for one file are not allowed.
See also @code{file-nlinks} in @ref{File Attributes}.
See also @code{file-nlinks} in @ref{File Attributes}.
@end defun
@deffn Command rename-file filename newname &optional ok-if-already-exists
@ -1176,7 +1185,7 @@ In an interactive call, this function prompts for @var{filename} and
This command copies the file @var{oldname} to @var{newname}. An
error is signaled if @var{oldname} does not exist.
If @var{time} is non-@code{nil}, then this functions gives the new file
If @var{time} is non-@code{nil}, then this function gives the new file
the same last-modified time that the old one has. (This works on only
some operating systems.) If setting the time gets an error,
@code{copy-file} signals a @code{file-date-error} error.
@ -1579,9 +1588,9 @@ form.
@example
(file-relative-name "/foo/bar" "/foo/")
@result{} "bar")
@result{} "bar"
(file-relative-name "/foo/bar" "/hack/")
@result{} "/foo/bar")
@result{} "/foo/bar"
@end example
@end defun
@ -1653,38 +1662,55 @@ construct a name for such a file:
@example
(make-temp-name
(expand-file-name @var{name-of-application}
(or (getenv "TMPDIR")
"/tmp/")))
temporary-file-directory))
@end example
@cindex @code{TMPDIR} environment variable.
@noindent
The job of @code{make-temp-name} is to prevent two different users or
two different jobs from trying to use the same name.
This example uses the environment variable @code{TMPDIR} to specify the
directory, and if that is not specified, we use the directory
@file{/tmp/}. This is the standard way to choose the directory, and all
Emacs Lisp programs should use it.
two different jobs from trying to use the exact same file name. This
example uses the variable @code{temporary-file-directory} to decide
where to put the temporary file. All Emacs Lisp programs should
use @code{temporary-file-directory} for this purpose, to give the user
a uniform way to specify the directory for all temporary files.
@defun make-temp-name string
This function generates string that can be used as a unique name. The
name starts with @var{string}, and ends with a number that is different
in each Emacs job.
This function generates string that can be used as a unique file name.
The name starts with @var{string}, and contains a number that is
different in each Emacs job.
@example
@group
(make-temp-name "/tmp/foo")
@result{} "/tmp/foo021304"
@result{} "/tmp/foo232J6v"
@end group
@end example
To prevent conflicts among different libraries running in the same
Emacs, each Lisp program that uses @code{make-temp-name} should have its
own @var{string}. The number added to the end of the name distinguishes
between the same application running in different Emacs jobs.
own @var{string}. The number added to the end of @var{string}
distinguishes between the same application running in different Emacs
jobs. Additional added characters permit a large number of distinct
names even in one Emacs job.
@end defun
@defvar temporary-file-directory
@cindex @code{TMPDIR} environment variable.
@cindex @code{TMP} environment variable.
This variable specifies the directory name for creating temporary files.
Its value should be a directory name (@pxref{Directory Names}), but it
is good for Lisp programs to cope if the value is a file name instead.
(Using the value as the second argument to @code{expand-file-name} is a
good way to achieve that.)
The default value is determined in a reasonable way for your operating
system; on GNU and Unix systems it is based on the @code{TMP} and
@code{TMPDIR} environment variables.
Even if you do not use @code{make-temp-name} to choose the temporary
file's name, you should still use this variable to decide which
directory to put the file in.
@end defvar
@node File Name Completion
@subsection File Name Completion
@cindex file name completion subroutines
@ -1813,7 +1839,7 @@ is an example from the @code{completion} package:
On GNU and Unix systems, and on some other systems as well,
@code{convert-standard-filename} returns its argument unchanged. On
some other systems, it alters the name to fit the systems's conventions.
some other systems, it alters the name to fit the system's conventions.
For example, on MS-DOS the alterations made by this function include
converting a leading @samp{.} to @samp{_}, converting a @samp{_} in the
@ -1883,11 +1909,12 @@ specification including wildcard characters. If @var{wildcard} is
non-@code{nil}, that means treat @var{file} as a file specification with
wildcards.
If @var{full-directory-p} is non-@code{nil}, that the directory listing
is expected to show a complete directory. You should specify @code{t}
when @var{file} is a directory and switches do not contain @samp{-d}.
(The @samp{-d} option to @code{ls} says to describe a directory itself
as a file, rather than showing its contents.)
If @var{full-directory-p} is non-@code{nil}, that means the directory
listing is expected to show the full contents of a directory. You
should specify @code{t} when @var{file} is a directory and switches do
not contain @samp{-d}. (The @samp{-d} option to @code{ls} says to
describe a directory itself as a file, rather than showing its
contents.)
This function works by running a directory listing program whose name is
in the variable @code{insert-directory-program}. If @var{wildcard} is
@ -2230,7 +2257,7 @@ The argument @var{format} is a list of format names. If @var{format} is
@defvar auto-save-file-format
This variable specifies the format to use for auto-saving. Its value is
a list of format names, just like the value of
@code{buffer-file-format}; but it is used instead of
@code{buffer-file-format} for writing auto-save files. This variable
is always buffer-local in all buffers.
@code{buffer-file-format}; however, it is used instead of
@code{buffer-file-format} for writing auto-save files. This variable is
always buffer-local in all buffers.
@end defvar

134
lispref/frames.texi
View file

@ -13,11 +13,11 @@ perhaps a minibuffer window), which you can subdivide vertically or
horizontally into smaller windows.
@cindex terminal frame
@cindex X window frame
When Emacs runs on a text-only terminal, it starts with one
@dfn{terminal frame}. If you create additional ones, Emacs displays
one and only one at any given time---on the terminal screen, of course.
@cindex window frame
When Emacs communicates directly with a supported window system, such
as X Windows, it does not have a terminal frame; instead, it starts with
a single @dfn{window frame}, but you can create more, and Emacs can
@ -77,14 +77,14 @@ window system Emacs uses to display its frames. @xref{Window Frame
Parameters}, for documentation of individual parameters you can specify.
@end defun
@tindex before-make-frame-hook
@defvar before-make-frame-hook
@tindex before-make-frame-hook
A normal hook run by @code{make-frame} before it actually creates the
frame.
@end defvar
@tindex after-make-frame-hook
@defvar after-make-frame-hook
@tindex after-make-frame-hook
An abnormal hook run by @code{make-frame} after it creates the frame.
Each function in @code{after-make-frame-hook} receives one argument, the
frame just created.
@ -265,6 +265,11 @@ window frame; of these, @code{name}, @code{title}, @code{height},
meaningful information in terminal frames.
@table @code
@item display
The display on which to open this frame. It should be a string of the
form @code{"@var{host}:@var{dpy}.@var{screen}"}, just like the
@code{DISPLAY} environment variable.
@item title
If a frame has a non-@code{nil} title, it appears in the window system's
border for the frame, and also in the mode line of windows in that frame
@ -283,11 +288,6 @@ If you specify the frame name explicitly when you create the frame, the
name is also used (instead of the name of the Emacs executable) when
looking up X resources for the frame.
@item display
The display on which to open this frame. It should be a string of the
form @code{"@var{host}:@var{dpy}.@var{screen}"}, just like the
@code{DISPLAY} environment variable.
@item left
The screen position of the left edge, in pixels, with respect to the
left edge of the screen. The value may be a positive number @var{pos},
@ -382,7 +382,8 @@ ordered most-recently-selected first.
@item font
The name of the font for displaying text in the frame. This is a
string.
string, either a valid font name for your system or the name of an Emacs
fontset (@pxref{Fontsets}).
@item auto-raise
Whether selecting the frame raises it (non-@code{nil} means yes).
@ -457,12 +458,14 @@ The default is 1. @xref{Menu Bar}. (In Emacs versions that use the X
toolkit, there is only one menu bar line; all that matters about the
number you specify is whether it is greater than zero.)
@ignore
@item parent-id
@c ??? Not yet working.
The X window number of the window that should be the parent of this one.
Specifying this lets you create an Emacs window inside some other
application's window. (It is not certain this will be implemented; try
it and see if it works.)
@end ignore
@end table
@node Size and Position
@ -820,8 +823,8 @@ The redirection lasts until @code{redirect-frame-focus} is called to
change it.
@end defun
@tindex focus-follows-mouse
@defopt focus-follows-mouse
@tindex focus-follows-mouse
This option is how you inform Emacs whether the window manager transfers
focus when the user moves the mouse. Non-@code{nil} says that it does.
When this is so, the command @code{other-frame} moves the mouse to a
@ -895,12 +898,12 @@ on the screen.
You can raise and lower Emacs frame Windows with these functions:
@deffn Command raise-frame frame
This function raises frame @var{frame}.
@deffn Command raise-frame &optional frame
This function raises frame @var{frame} (default, the selected frame).
@end deffn
@deffn Command lower-frame frame
This function lowers frame @var{frame}.
@deffn Command lower-frame &optional frame
This function lowers frame @var{frame} (default, the selected frame).
@end deffn
@defopt minibuffer-auto-raise
@ -1022,7 +1025,8 @@ the top left corner of the inside of @var{frame}.
This function @dfn{warps the mouse} to position @var{x}, @var{y} in
frame @var{frame}. The arguments @var{x} and @var{y} are integers,
giving the position in characters relative to the top left corner of the
inside of @var{frame}.
inside of @var{frame}. If @var{frame} is not visible, this function
does nothing. The return value is not significant.
@end defun
@defun mouse-pixel-position
@ -1034,6 +1038,9 @@ coordinates in units of pixels rather than units of characters.
This function warps the mouse like @code{set-mouse-position} except that
@var{x} and @var{y} are in units of pixels rather than units of
characters. These coordinates are not required to be within the frame.
If @var{frame} is not visible, this function does nothing. The return
value is not significant.
@end defun
@need 3000
@ -1266,6 +1273,101 @@ for @var{maximum} can make this function much faster, in cases where
many fonts match the pattern.
@end defun
@node Fontsets
@section Fontsets
A @dfn{fontset} is a list of fonts, each assigned to a range of
character codes. An individual font cannot display the whole range of
characters that Emacs supports, but a fontset can. Fontsets have names,
just as fonts do, and you can use a fontset name in place of a font name
when you specify the ``font'' for a frame or a face. Here is
information about defining a fontset under Lisp program control.
@defun create-fontset-from-fontset-spec fontset-spec &optional style noerror
This function defines a new fontset according to the specification
string @var{fontset-spec}. The string should have this format:
@smallexample
@var{fontpattern}, @r{[}@var{charsetname}:@var{fontname}@r{]@dots{}}
@end smallexample
@noindent
Whitespace characters before and after the commas are ignored.
The first part of the string, @var{fontpattern}, should have the form of
a standard X font name, except that the last two fields should be
@samp{fontset-@var{alias}}.
Each fontset has two names, one long and one short. The long name is
@var{fontpattern} in its entirety. The short name is
@samp{fontset-@var{alias}}. You can refer to the fontset by either
name. If a fontset with the same name already exists, an error is
signaled, unless @var{noerror} is non-@code{nil}, in which case this
function does nothing.
The specification string also says which fonts to use in the fontset.
See below for the details.
@end defun
If optional argument @var{style} is specified, it specifies a way to
modify the fontset. It should be one of @code{bold}, @code{italic}, and
@code{bold-italic}, and it says to find the bold, italic or bold-italic
version of each font if possible.
The construct @samp{@var{charset}:@var{font}} specifies which font to
use (in this fontset) for one particular character set. Here,
@var{charset} is the name of a character set, and @var{font} is the font
to use for that character set. You can use this construct any number of
times in the specification string.
For the remaining character sets, those that you don't specify
explicitly, Emacs chooses a font based on @var{fontpattern}: it replaces
@samp{fontset-@var{alias}} with a value that names one character set.
For the @sc{ASCII} character set, @samp{fontset-@var{alias}} is replaced
with @samp{ISO8859-1}.
In addition, when several consecutive fields are wildcards, Emacs
collapses them into a single wildcard. This is to prevent use of
auto-scaled fonts. Fonts made by scaling larger fonts are not usable
for editing, and scaling a smaller font is not useful because it is
better to use the smaller font in its own size, which Emacs does.
Thus if @var{fontpattern} is this,
@example
-*-fixed-medium-r-normal-*-24-*-*-*-*-*-fontset-24
@end example
@noindent
the font specification for ASCII characters would be this:
@example
-*-fixed-medium-r-normal-*-24-*-ISO8859-1
@end example
@noindent
and the font specification for Chinese GB2312 characters would be this:
@example
-*-fixed-medium-r-normal-*-24-*-gb2312*-*
@end example
You may not have any Chinese font matching the above font
specification. Most X distributions include only Chinese fonts that
have @samp{song ti} or @samp{fangsong ti} in @var{family} field. In
such a case, @samp{Fontset-@var{n}} can be specified as below:
@smallexample
Emacs.Fontset-0: -*-fixed-medium-r-normal-*-24-*-*-*-*-*-fontset-24,\
chinese-gb2312:-*-*-medium-r-normal-*-24-*-gb2312*-*
@end smallexample
@noindent
Then, the font specifications for all but Chinese GB2312 characters have
@samp{fixed} in the @var{family} field, and the font specification for
Chinese GB2312 characters has a wild card @samp{*} in the @var{family}
field.
@node Color Names
@section Color Names
@ -1422,7 +1524,7 @@ This function returns the number of color cells the screen supports.
@ignore
@defvar x-no-window-manager
This variable's value is is @code{t} if no X window manager is in use.
This variable's value is @code{t} if no X window manager is in use.
@end defvar
@end ignore

47
lispref/functions.texi
View file

@ -54,11 +54,11 @@ such as @code{car} or @code{append}. These functions are also called
@dfn{built-in} functions or @dfn{subrs}. (Special forms are also
considered primitives.)
Usually the reason we implement a function as a primitive is because it
is fundamental, because it provides a low-level interface to operating
system services, or because it needs to run fast. Primitives can be
modified or added only by changing the C sources and recompiling the
editor. See @ref{Writing Emacs Primitives}.
Usually the reason we implement a function as a primitive is either
because it is fundamental, because it provides a low-level interface to
operating system services, or because it needs to run fast. Primitives
can be modified or added only by changing the C sources and recompiling
the editor. See @ref{Writing Emacs Primitives}.
@item lambda expression
A @dfn{lambda expression} is a function written in Lisp.
@ -110,8 +110,8 @@ A @dfn{byte-code function} is a function that has been compiled by the
byte compiler. @xref{Byte-Code Type}.
@end table
@tindex functionp
@defun functionp object
@tindex functionp
This function returns @code{t} if @var{object} is any kind of function,
or a special form or macro.
@end defun
@ -458,11 +458,13 @@ one symbol, this is just a matter of convenience. It is easy to store
it in several symbols using @code{fset}; then each of the symbols is
equally well a name for the same function.
A symbol used as a function name may also be used as a variable;
these two uses of a symbol are independent and do not conflict.
(Some Lisp dialects, such as Scheme, do not distinguish between a
symbol's value and its function definition; a symbol's value as a variable
is also its function definition.)
A symbol used as a function name may also be used as a variable; these
two uses of a symbol are independent and do not conflict. (Some Lisp
dialects, such as Scheme, do not distinguish between a symbol's value
and its function definition; a symbol's value as a variable is also its
function definition.) If you have not given a symbol a function
definition, you cannot use it as a function; whether the symbol has a
value as a variable makes no difference to this.
@node Defining Functions
@section Defining Functions
@ -581,7 +583,7 @@ which function to call, and how many arguments to give it, when you
write the program. Usually that's just what you want. Occasionally you
need to compute at run time which function to call. To do that, use the
function @code{funcall}. When you also need to determine at run time
how may arguments to pass, use @code{apply}.
how many arguments to pass, use @code{apply}.
@defun funcall function &rest arguments
@code{funcall} calls @var{function} with @var{arguments}, and returns
@ -846,7 +848,8 @@ of simple quotation to quote the anonymous function, like this:
@example
@group
(defun double-property (symbol prop)
(change-property symbol prop (function (lambda (x) (* 2 x)))))
(change-property symbol prop
(function (lambda (x) (* 2 x)))))
@end group
@end example
@ -864,7 +867,7 @@ definition which uses ordinary @code{quote}, the argument passed to
@noindent
The Lisp compiler cannot assume this list is a function, even though it
looks like one, since it does not know what @code{change-property} will
do with the list. Perhaps will check whether the @sc{car} of the third
do with the list. Perhaps it will check whether the @sc{car} of the third
element is the symbol @code{*}! Using @code{function} tells the
compiler it is safe to go ahead and compile the constant function.
@ -874,6 +877,20 @@ comment:
@example
(function @var{symbol}) @equiv{} (quote @var{symbol}) @equiv{} '@var{symbol}
@end example
The read syntax @code{#'} is a short-hand for using @code{function}.
For example,
@example
#'(lambda (x) (* x x))
@end example
@noindent
is equivalent to
@example
(function (lambda (x) (* x x)))
@end example
@defspec function function-object
@ -952,7 +969,7 @@ is a legitimate function.
@defun fmakunbound symbol
This function makes @var{symbol}'s function cell void, so that a
subsequent attempt to access this cell will cause a @code{void-function}
error. (See also @code{makunbound}, in @ref{Local Variables}.)
error. (See also @code{makunbound}, in @ref{Void Variables}.)
@example
@group

33
lispref/help.texi
View file

@ -415,6 +415,15 @@ Emacs buffers are usually displayed).
@end smallexample
@end defun
@defun read-kbd-macro string
This function is used mainly for operating on keyboard macros, but it
can also be used as a rough inverse for @code{key-description}. You
call it with a string containing key descriptions, separated by spaces;
it returns a string or vector containing the corresponding events.
(This may or may not be a single valid key sequence, depending on what
events you use; @pxref{Keymap Terminology}.)
@end defun
@node Help Functions
@section Help Functions
@ -431,8 +440,9 @@ named @samp{*Help*}, each with a one-line description taken from the
beginning of its documentation string.
@c Emacs 19 feature
If @var{do-all} is non-@code{nil}, then @code{apropos} also shows
key bindings for the functions that are found.
If @var{do-all} is non-@code{nil}, then @code{apropos} also shows key
bindings for the functions that are found; it also shows all symbols,
even those that are neither functions nor variables.
In the first of the following examples, @code{apropos} finds all the
symbols with names containing @samp{exec}. (We don't show here the
@ -481,10 +491,10 @@ Documentation}.
@defvar help-char
The value of this variable is the help character---the character that
Emacs recognizes as meaning Help. By default, it stands for 8, which is
@kbd{C-h}. When Emacs reads this character, if @code{help-form} is
non-@code{nil} Lisp expression, it evaluates that expression, and
displays the result in a window if it is a string.
Emacs recognizes as meaning Help. By default, its value is 8, which
stands for @kbd{C-h}. When Emacs reads this character, if
@code{help-form} is a non-@code{nil} Lisp expression, it evaluates that
expression, and displays the result in a window if it is a string.
Usually the value of @code{help-form}'s value is @code{nil}. Then the
help character has no special meaning at the level of command input, and
@ -498,8 +508,8 @@ binding as a subcommand of the prefix key, it runs
subcommands of the prefix key.
@end defvar
@tindex help-event-list
@defvar help-event-list
@tindex help-event-list
The value of this variable is a list of event types that serve as
alternative ``help characters.'' These events are handled just like the
event specified by @code{help-char}.
@ -534,11 +544,10 @@ prefix described consists of all but the last event of that key
sequence. (The last event is, presumably, the help character.)
@end defun
The following two functions are found in the library @file{helper}.
They are for modes that want to provide help without relinquishing
control, such as the ``electric'' modes. You must load that library
with @code{(require 'helper)} in order to use them. Their names begin
with @samp{Helper} to distinguish them from the ordinary help functions.
The following two functions are meant for modes that want to provide
help without relinquishing control, such as the ``electric'' modes.
Their names begin with @samp{Helper} to distinguish them from the
ordinary help functions.
@deffn Command Helper-describe-bindings
This command pops up a window displaying a help buffer containing a

2
lispref/hooks.texi
View file

@ -30,7 +30,7 @@ however, we have renamed all of those.)
@c !!! need xref to where each hook is documented or else document it
@c by specifying what is expected, and when it is called relative to
@c mode initialization.)
@c mode initialization.
@table @code
@item activate-mark-hook

10
lispref/internals.texi
View file

@ -302,6 +302,14 @@ The number of floats in use.
@c Emacs 19 feature
The number of floats for which space has been obtained from the
operating system, but that are not currently being used.
@item used-intervals
The number of intervals in use. Intervals are an internal
data structure used for representing text properties.
@item free-intervals
The number of intervals for which space has been obtained
from the operating system, but that are not currently being used.
@end table
@end deffn
@ -778,7 +786,7 @@ This field is non-@code{nil} if the buffer's mark is active.
@item local_var_alist
This field contains the association list describing the buffer-local
variable bindings of this buffer, not including the built-in
buffer-local bindings that that have special slots in the buffer object.
buffer-local bindings that have special slots in the buffer object.
(Those slots are omitted from this table.) @xref{Buffer-Local
Variables}.

89
lispref/intro.texi
View file

@ -418,12 +418,17 @@ closely integrated with the editing facilities; thus, editing commands
are functions that can also conveniently be called from Lisp programs,
and parameters for customization are ordinary Lisp variables.
This manual describes Emacs Lisp, presuming considerable familiarity
with the use of Emacs for editing. (See @cite{The GNU Emacs Manual}
for this basic information.) Generally speaking, the earlier chapters
describe features of Emacs Lisp that have counterparts in many
programming languages, and later chapters describe features that are
peculiar to Emacs Lisp or relate specifically to editing.
This manual attempts to be a full description of Emacs Lisp. For a
beginner's introduction to Emacs Lisp, see @cite{An Introduction to
Emacs Lisp Programming}, by Bob Chassell, also published by the Free
Software Foundation. This manual presumes considerable familiarity with
the use of Emacs for editing; see @cite{The GNU Emacs Manual} for this
basic information.
Generally speaking, the earlier chapters describe features of Emacs
Lisp that have counterparts in many programming languages, and later
chapters describe features that are peculiar to Emacs Lisp or relate
specifically to editing.
This is edition 2.5.
@ -431,6 +436,7 @@ peculiar to Emacs Lisp or relate specifically to editing.
* Caveats:: Flaws and a request for help.
* Lisp History:: Emacs Lisp is descended from Maclisp.
* Conventions:: How the manual is formatted.
* Version Info:: Which Emacs version is running?
* Acknowledgements:: The authors, editors, and sponsors of this manual.
@end menu
@ -474,7 +480,7 @@ which you are criticizing.
Please mail comments and corrections to
@example
bug-lisp-manual@@prep.ai.mit.edu
bug-lisp-manual@@gnu.org
@end example
@noindent
@ -483,7 +489,7 @@ apply the corrections. Months, and sometimes years, go by between
updates. So please attach no significance to the lack of a reply---your
mail @emph{will} be acted on in due time. If you want to contact the
Emacs maintainers more quickly, send mail to
@code{bug-gnu-emacs@@prep.ai.mit.edu}.
@code{bug-gnu-emacs@@gnu.org}.
@display
--Bil Lewis, Dan LaLiberte, Richard Stallman
@ -493,33 +499,38 @@ Emacs maintainers more quickly, send mail to
@section Lisp History
@cindex Lisp history
Lisp (LISt Processing language) was first developed in the late 1950's
Lisp (LISt Processing language) was first developed in the late 1950s
at the Massachusetts Institute of Technology for research in artificial
intelligence. The great power of the Lisp language makes it superior
intelligence. The great power of the Lisp language makes it ideal
for other purposes as well, such as writing editing commands.
@cindex Maclisp
@cindex Common Lisp
Dozens of Lisp implementations have been built over the years, each
with its own idiosyncrasies. Many of them were inspired by Maclisp,
which was written in the 1960's at MIT's Project MAC. Eventually the
which was written in the 1960s at MIT's Project MAC. Eventually the
implementors of the descendants of Maclisp came together and developed a
standard for Lisp systems, called Common Lisp. In the mean time, Gerry
standard for Lisp systems, called Common Lisp. In the meantime, Gerry
Sussman and Guy Steele at MIT developed a simplified but very powerful
dialect of Lisp, called Scheme.
GNU Emacs Lisp is largely inspired by Maclisp, and a little by Common
Lisp. If you know Common Lisp, you will notice many similarities.
However, many of the features of Common Lisp have been omitted or
However, many features of Common Lisp have been omitted or
simplified in order to reduce the memory requirements of GNU Emacs.
Sometimes the simplifications are so drastic that a Common Lisp user
might be very confused. We will occasionally point out how GNU Emacs
Lisp differs from Common Lisp. If you don't know Common Lisp, don't
worry about it; this manual is self-contained.
@pindex cl
A certain amount of Common Lisp emulation is available via the
@file{cl} library @xref{Top,, Common Lisp Extension, cl, Common Lisp
Extensions}.
Emacs Lisp is not at all influenced by Scheme; but the GNU project has
an implementation of Scheme, called Guile. We use Guile for
extensibility in all new GNU software that calls for extensibility.
an implementation of Scheme, called Guile. We use Guile in all new GNU
software that calls for extensibility.
@node Conventions
@section Conventions
@ -531,23 +542,22 @@ manual. You may want to skip this section and refer back to it later.
* Some Terms:: Explanation of terms we use in this manual.
* nil and t:: How the symbols @code{nil} and @code{t} are used.
* Evaluation Notation:: The format we use for examples of evaluation.
* Printing Notation:: The format we use for examples that print output.
* Printing Notation:: The format we use when examples print text.
* Error Messages:: The format we use for examples of errors.
* Buffer Text Notation:: The format we use for buffer contents in examples.
* Format of Descriptions:: Notation for describing functions, variables, etc.
* Version Info:: Which Emacs version is running?
@end menu
@node Some Terms
@subsection Some Terms
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 Lisp objects, and vice
printer'' refer to those routines in Lisp that convert 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,
including those you write.
addressed as ``you''. ``The user'' is the person who uses Lisp
programs, including those you write.
@cindex fonts
Examples of Lisp code appear in this font or form: @code{(list 1 2
@ -590,7 +600,8 @@ in Lisp programs also.
is considered to be @var{true}. However, @code{t} is the preferred way
to represent the truth value @var{true}. When you need to choose a
value which represents @var{true}, and there is no other basis for
choosing, use @code{t}. The symbol @code{t} always has value @code{t}.
choosing, use @code{t}. The symbol @code{t} always has the value
@code{t}.
In Emacs Lisp, @code{nil} and @code{t} are special symbols that always
evaluate to themselves. This is so that you do not need to quote them
@ -618,7 +629,7 @@ You can read this as ``@code{(car '(1 2))} evaluates to 1''.
When a form is a macro call, it expands into a new form for Lisp to
evaluate. We show the result of the expansion with
@samp{@expansion{}}. We may or may not show the actual result of the
@samp{@expansion{}}. We may or may not show the result of the
evaluation of the expanded form.
@example
@ -741,10 +752,11 @@ indicates that the subsequent arguments may be omitted (omitted
arguments default to @code{nil}). Do not write @code{&optional} when
you call the function.
The keyword @code{&rest} (which will always be followed by a single
argument name) indicates that any number of arguments can follow. The value
of the single following arguments name will be a list of all these arguments.
Do not write @code{&rest} when you call the function.
The keyword @code{&rest} (which must be followed by a single argument
name) indicates that any number of arguments can follow. The single
following argument name will have a value, as a variable, which is a
list of all these remaining arguments. Do not write @code{&rest} when
you call the function.
Here is a description of an imaginary function @code{foo}:
@ -791,7 +803,7 @@ interactively; macros process their arguments differently from functions
Special form descriptions use a more complex notation to specify
optional and repeated arguments because they can break the argument
list down into separate arguments in more complicated ways.
@samp{@code{@r{[}@var{optional-arg}@r{]}}} means that @var{optional-arg} is
@samp{@r{[}@var{optional-arg}@r{]}} means that @var{optional-arg} is
optional and @samp{@var{repeated-args}@dots{}} stands for zero or more
arguments. Parentheses are used when several arguments are grouped into
additional levels of list structure. Here is an example:
@ -800,7 +812,7 @@ additional levels of list structure. Here is an example:
This imaginary special form implements a loop that executes the
@var{body} forms and then increments the variable @var{var} on each
iteration. On the first iteration, the variable has the value
@var{from}; on subsequent iterations, it is incremented by 1 (or by
@var{from}; on subsequent iterations, it is incremented by one (or by
@var{inc} if that is given). The loop exits before executing @var{body}
if @var{var} equals @var{to}. Here is an example:
@ -811,7 +823,7 @@ if @var{var} equals @var{to}. Here is an example:
(terpri))
@end example
If @var{from} and @var{to} are omitted, then @var{var} is bound to
If @var{from} and @var{to} are omitted, @var{var} is bound to
@code{nil} before the loop begins, and the loop exits if @var{var} is
non-@code{nil} at the beginning of an iteration. Here is an example:
@ -855,33 +867,34 @@ replaced by `User Option'.
@node Version Info
@section Version Information
These functions and variables provide information about which
version of Emacs is in use.
These facilities provide information about which version of Emacs is
in use.
@deffn Command emacs-version
This function returns a string describing the version of Emacs that is
running. It is useful to include this string in bug reports.
@example
@smallexample
@group
(emacs-version)
@result{} "GNU Emacs 20.3.5 (i486-pc-linux-gnulibc1, X toolkit)
of Sat Feb 14 1998 on psilocin.gnu.org"
@end group
@end example
@end smallexample
Called interactively, the function prints the same information in the
echo area.
@end deffn
@defvar emacs-build-time
The value of this variable is the time at which Emacs was built at the
local site.
The value of this variable indicates the time at which Emacs was built
at the local site. It is a list of three integers, like the value
of @code{current-time} (@pxref{Time of Day}).
@example
@group
emacs-build-time
@result{} "Tue Jun 6 14:55:57 1995"
@result{} (13623 62065 344633)
@end group
@end example
@end defvar
@ -893,7 +906,7 @@ really part of the Emacs release version number; it is incremented each
time you build Emacs in any given directory.
@end defvar
The following two variables have existed since Emacs version 19.23,
The following two variables have existed since Emacs version 19.23:
@defvar emacs-major-version
The major version number of Emacs, as an integer. For Emacs version

193
lispref/keymaps.texi
View file

@ -133,11 +133,11 @@ keymaps}.
When a keymap contains a vector, it always defines a binding for each
@sc{ASCII} character, even if the vector contains @code{nil} for that
character. Such a binding of @code{nil} overrides any default key
binding in the keymap. However, default bindings are still meaningful
for events that are not @sc{ASCII} characters. A binding of @code{nil}
does @emph{not} override lower-precedence keymaps; thus, if the local
map gives a binding of @code{nil}, Emacs uses the binding from the
global map.
binding in the keymap, for @sc{ASCII} characters. However, default
bindings are still meaningful for events other than @sc{ASCII}
characters. A binding of @code{nil} does @emph{not} override
lower-precedence keymaps; thus, if the local map gives a binding of
@code{nil}, Emacs uses the binding from the global map.
@item @var{string}
@cindex keymap prompt string
@ -350,7 +350,7 @@ This map is also the function definition of @code{ESC-prefix}.
@item
@cindex @kbd{C-h}
@code{help-map} is the global definitions for the @kbd{C-h} prefix key.
@code{help-map} is the global keymap for the @kbd{C-h} prefix key.
@item
@cindex @kbd{C-c}
@ -365,8 +365,8 @@ mode-specific bindings.
@cindex @kbd{C-x}
@vindex ctl-x-map
@findex Control-X-prefix
@code{ctl-x-map} is the global key map used for the @kbd{C-x} prefix
key. This map is found via the function definition of the symbol
@code{ctl-x-map} is the global keymap used for the @kbd{C-x} prefix key.
This map is found via the function cell of the symbol
@code{Control-X-prefix}.
@item
@ -395,7 +395,7 @@ that have no special names.
that follows the prefix key. (It may instead be a symbol whose function
definition is a keymap. The effect is the same, but the symbol serves
as a name for the prefix key.) Thus, the binding of @kbd{C-x} is the
symbol @code{Control-X-prefix}, whose function definition is the keymap
symbol @code{Control-X-prefix}, whose function cell holds the keymap
for @kbd{C-x} commands. (The same keymap is also the value of
@code{ctl-x-map}.)
@ -472,7 +472,7 @@ local keymap is always active except when @code{overriding-local-map}
overrides it. Text properties can specify an alternative local map for
certain parts of the buffer; see @ref{Special Properties}.
Each minor mode may have a keymap; if it does, the keymap is active
Each minor mode can have a keymap; if it does, the keymap is active
when the minor mode is enabled.
The variable @code{overriding-local-map}, if non-@code{nil}, specifies
@ -485,11 +485,12 @@ order of decreasing precedence, until it finds a binding in one of the
maps. The procedure for searching a single keymap is called @dfn{key
lookup}; see @ref{Key Lookup}.
Normally, Emacs first searches for the key in the minor mode
maps (one map at a time); if they do not supply a binding for the key,
Emacs searches the local map; if that too has no binding, Emacs then
searches the global map. However, if @code{overriding-local-map} is
non-@code{nil}, Emacs searches that map first, before the global map.
Normally, Emacs first searches for the key in the minor mode maps, in
the order specified by @code{minor-mode-map-alist}; if they do not
supply a binding for the key, Emacs searches the local map; if that too
has no binding, Emacs then searches the global map. However, if
@code{overriding-local-map} is non-@code{nil}, Emacs searches that map
first, before the global map.
@cindex major mode keymap
Since every buffer that uses the same major mode normally uses the
@ -506,6 +507,9 @@ only when the mode is used for the first time in a session.
The minibuffer has local keymaps, too; they contain various completion
and exit commands. @xref{Intro to Minibuffers}.
Emacs has other keymaps that are used in a different way---translating
events within @code{read-key-sequence}. @xref{Translating Input}.
@xref{Standard Keymaps}, for a list of standard keymaps.
@defvar global-map
@ -604,14 +608,17 @@ modes. See also @code{minor-mode-key-binding} (@pxref{Functions for Key
Lookup}).
@end defvar
@tindex minor-mode-overriding-map-alist
@defvar minor-mode-overriding-map-alist
@tindex minor-mode-overriding-map-alist
This variable allows major modes to override the key bindings for
particular minor modes. The elements of this alist look like the
elements of @code{minor-mode-map-alist}: @code{(@var{variable}
. @var{keymap})}. If a variable appears an element
@code{minor-mode-overriding-map-alist}, that element overrides any
element for the same variable in @code{minor-mode-map-alist}.
. @var{keymap})}.
If a variable appears an element of
@code{minor-mode-overriding-map-alist}, the map specified by that
element totally replaces any map specified for the same variable in
@code{minor-mode-map-alist}.
@code{minor-mode-overriding-map-alist} is automatically buffer-local in
all buffers.
@ -1414,7 +1421,7 @@ an indirect definition itself.
@end smallexample
@end defun
@deffn Command describe-bindings prefix
@deffn Command describe-bindings &optional prefix
This function creates a listing of all current key bindings, and
displays it in a buffer named @samp{*Help*}. The text is grouped by
modes---minor modes first, then the major mode, then global bindings.
@ -1475,8 +1482,12 @@ an existing menu, you can specify its position in the menu using
@code{define-key-after} (@pxref{Modifying Menus}).
@menu
* Simple Menu Items::
* Extended Menu Items::
* Simple Menu Items:: A simple kind of menu key binding,
limited in capabilities.
* Alias Menu Items:: Using command aliases in menu items.
* Extended Menu Items:: More powerful menu item definitions
let you specify keywords to enable
various features.
@end menu
@node Simple Menu Items
@ -1489,6 +1500,7 @@ looks like this:
(@var{item-string} . @var{real-binding})
@end example
@noindent
The @sc{car}, @var{item-string}, is the string to be displayed in the
menu. It should be short---preferably one to three words. It should
describe the action of the command it corresponds to.
@ -1540,35 +1552,9 @@ Don't put these sublists in the menu item yourself; menu display
calculates them automatically. Don't mention keyboard equivalents in
the item strings themselves, since that is redundant.
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
@code{toggle-read-only} and gives them different enable conditions:
@example
(defalias 'make-read-only 'toggle-read-only)
(put 'make-read-only 'menu-enable '(not buffer-read-only))
(defalias 'make-writable 'toggle-read-only)
(put 'make-writable 'menu-enable 'buffer-read-only)
@end example
When using aliases in menus, often it is useful to display the
equivalent key bindings for the ``real'' command name, not the aliases
(which typically don't have any key bindings except for the menu
itself). To request this, give the alias symbol a non-@code{nil}
@code{menu-alias} property. Thus,
@example
(put 'make-read-only 'menu-alias t)
(put 'make-writable 'menu-alias t)
@end example
@noindent
causes menu items for @code{make-read-only} and @code{make-writable} to
show the keyboard bindings for @code{toggle-read-only}.
@node Extended Menu Items
@subsubsection Extended Menu Items
@kindex menu-item
An extended-format menu item is a more flexible and also cleaner
alternative to the simple format. It consists of a list that starts
@ -1610,7 +1596,7 @@ not defined at all.
@item :help @var{help}
The value of this property, @var{help}, is the extra help string (not
currently used).
currently used by Emacs).
@item :button (@var{type} . @var{selected})
This property provides a way to define radio buttons and toggle buttons.
@ -1618,6 +1604,54 @@ The @sc{car}, @var{type}, says which: is should be @code{:toggle} or
@code{:radio}. The @sc{cdr}, @var{selected}, should be a form; the
result of evaluating it says whether this button is currently selected.
A @dfn{toggle} is a menu item which is labeled as either ``on'' or ``off''
according to the value of @var{selected}. The command itself should
toggle @var{selected}, setting it to @code{t} if it is @code{nil},
and to @code{nil} if it is @code{t}. Here is how the menu item
to toggle the @code{debug-on-error} flag is defined:
@example
(menu-item "Debug on Error" toggle-debug-on-error
:button (:toggle
. (and (boundp 'debug-on-error)
debug-on-error))
@end example
@noindent
This works because @code{toggle-debug-on-error} is defined as a command
which toggles the variable @code{debug-on-error}.
@dfn{Radio buttons} are a group of menu items, in which at any time one
and only one is ``selected.'' There should be a variable whose value
says which one is selected at any time. The @var{selected} form for
each radio button in the group should check whether the variable has the
right value for selecting that button. Clicking on the button should
set the variable so that the button you clicked on becomes selected.
@item :key-sequence @var{key-sequence}
This property specifies which key sequence is likely to be bound to the
same command invoked by this menu item. If you specify the right key
sequence, that makes preparing the menu for display run much faster.
If you specify the wrong key sequence, it has no effect; before Emacs
displays @var{key-sequence} in the menu, it verifies that
@var{key-sequence} is really equivalent to this menu item.
@item :key-sequence nil
This property indicates that there is normally no key binding which is
equivalent to this menu item. Using this property saves time in
preparing the menu for display, because Emacs does not need to search
the keymaps for a keyboard equivalent for this menu item.
However, if the user has rebound this item's definition to a key
sequence, Emacs ignores the @code{:keys} property and finds the keyboard
equivalent anyway.
@item :keys @var{string}
This property specifies that @var{string} is the string to display
as the keyboard equivalent for this menu item. You can use
the @samp{\\[...]} documentation construct in @var{string}.
@item :filter @var{filter-fn}
This property provides a way to compute the menu item dynamically.
The property value @var{filter-fn} should be a function of one argument;
@ -1625,6 +1659,38 @@ when it is called, its argument will be @var{real-binding}. The
function should return the binding to use instead.
@end table
@node Alias Menu Items
@subsubsection Alias Menu Items
Sometimes it is useful to make menu items that use the ``same''
command but with different enable conditions. The best way to do this
in Emacs now is with extended menu items; before that feature existed,
it could be done by defining alias commands and using them in menu
items. Here's an example that makes two aliases for
@code{toggle-read-only} and gives them different enable conditions:
@example
(defalias 'make-read-only 'toggle-read-only)
(put 'make-read-only 'menu-enable '(not buffer-read-only))
(defalias 'make-writable 'toggle-read-only)
(put 'make-writable 'menu-enable 'buffer-read-only)
@end example
When using aliases in menus, often it is useful to display the
equivalent key bindings for the ``real'' command name, not the aliases
(which typically don't have any key bindings except for the menu
itself). To request this, give the alias symbol a non-@code{nil}
@code{menu-alias} property. Thus,
@example
(put 'make-read-only 'menu-alias t)
(put 'make-writable 'menu-alias t)
@end example
@noindent
causes menu items for @code{make-read-only} and @code{make-writable} to
show the keyboard bindings for @code{toggle-read-only}.
@node Mouse Menus
@subsection Menus and the Mouse
@ -1708,7 +1774,8 @@ for @key{SPC}.
Here is a complete example of defining a menu keymap. It is the
definition of the @samp{Print} submenu in the @samp{Tools} menu in the
menu bar. First we create the keymap, and give it a name:
menu bar, and it uses the simple menu item format (@pxref{Simple Menu
Items}). First we create the keymap, and give it a name:
@example
(defvar menu-bar-print-menu (make-sparse-keymap "Print"))
@ -1771,7 +1838,29 @@ command.
can do it this way:
@example
(define-key global-map [C-S-down-mouse-1] menu-bar-print-menu)
(define-key global-map [C-S-down-mouse-1]
menu-bar-print-menu)
@end example
We could equally well use an extended menu item (@pxref{Extended Menu
Items}) for @code{print-region}, like this:
@example
(define-key menu-bar-print-menu [print-region]
'(menu-item "Print Region" print-region
:enable (mark-active)))
@end example
@noindent
With the extended menu item, the enable condition is specified
inside the menu item itself. If we wanted to make this
item disappear from the menu entirely when the mark is inactive,
we could do it this way:
@example
(define-key menu-bar-print-menu [print-region]
'(menu-item "Print Region" print-region
:visible (mark-active)))
@end example
@node Menu Bar

27
lispref/lists.texi
View file

@ -357,8 +357,8 @@ If @var{n} is zero or negative, @code{nthcdr} returns all of
@end example
@end defun
@tindex safe-length
@defun safe-length list
@tindex safe-length
This function returns the length of @var{list}, with no risk
of either an error or an infinite loop.
@ -371,24 +371,24 @@ number of distinct elements.
worried that it may be circular, is with @code{length}. @xref{Sequence
Functions}.
@tindex caar
@defun caar cons-cell
@tindex caar
This is the same as @code{(car (car @var{cons-cell}))}.
@end defun
@tindex cadr
@defun cadr cons-cell
@tindex cadr
This is the same as @code{(car (cdr @var{cons-cell}))}
or @code{(nth 1 @var{cons-cell})}.
@end defun
@tindex cdar
@defun cdar cons-cell
@tindex cdar
This is the same as @code{(cdr (car @var{cons-cell}))}.
@end defun
@tindex cddr
@defun cddr cons-cell
@tindex cddr
This is the same as @code{(cdr (cdr @var{cons-cell}))}
or @code{(nthcdr 2 @var{cons-cell})}.
@end defun
@ -572,8 +572,8 @@ Here we show the use of vectors and strings as arguments to @code{append}:
@end group
@end example
With the help of @code{apply}, we can append all the lists in a list of
lists:
With the help of @code{apply} (@pxref{Calling Functions}), we can append
all the lists in a list of lists:
@example
@group
@ -1030,6 +1030,15 @@ arguments. It is called with two elements of @var{list}. To get an
increasing order sort, the @var{predicate} should return @code{t} if the
first element is ``less than'' the second, or @code{nil} if not.
The comparison function @var{predicate} must give reliable results for
any given pair of arguments, at least within a single call to
@code{sort}. It must be @dfn{antisymmetric}; that is, if @var{a} is
less than @var{b}, @var{b} must not be less than @var{a}. It must be
@dfn{transitive}---that is, if @var{a} is less than @var{b}, and @var{b}
is less than @var{c}, then @var{a} must be less than @var{c}. If you
use a comparison function which does not meet these requirements, the
result of @code{sort} is unpredictable.
The destructive aspect of @code{sort} is that it rearranges the cons
cells forming @var{list} by changing @sc{cdr}s. A nondestructive sort
function would create new cons cells to store the elements in their
@ -1338,6 +1347,10 @@ Here is another example, in which the keys and values are not symbols:
@end smallexample
@end defun
The functions @code{assoc-ignore-representation} and
@code{assoc-ignore-case} are much like @code{assoc} except using
@code{compare-strings} to do the comparison. @xref{Text Comparison}.
@defun rassoc value alist
This function returns the first association with value @var{value} in
@var{alist}. It returns @code{nil} if no association in @var{alist} has

176
lispref/loading.texi
View file

@ -35,6 +35,8 @@ containing Lisp code.
@menu
* How Programs Do Loading:: The @code{load} function and others.
* Library Search:: Finding a library to load.
* Loading Non-ASCII:: Non-@sc{ASCII} characters in Emacs Lisp files.
* Autoload:: Setting up a function to autoload.
* Repeated Loading:: Precautions about loading a file twice.
* Named Features:: Loading a library if it isn't already loaded.
@ -53,7 +55,7 @@ function's real definition (@pxref{Autoload}). @code{require} loads a
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
@defun load filename &optional missing-ok nomessage nosuffix must-suffix
This function finds and opens a file of Lisp code, evaluates all the
forms in it, and closes the file.
@ -74,6 +76,12 @@ must specify the precise file name you want. By specifying the precise
file name and using @code{t} for @var{nosuffix}, you can prevent
perverse file names such as @file{foo.el.el} from being tried.
If the optional argument @var{must-suffix} is non-@code{nil}, then
@code{load} insists that the file name used must end in either
@samp{.el} or @samp{.elc}, unless it contains an explicit directory
name. If @var{filename} does not contain an explicit directory name,
and does not end in a suffix, then @code{load} insists on adding one.
If @var{filename} is a relative file name, such as @file{foo} or
@file{baz/foo.bar}, @code{load} searches for the file using the variable
@code{load-path}. It appends @var{filename} to each of the directories
@ -82,7 +90,7 @@ matches. The current default directory is tried only if it is specified
in @code{load-path}, where @code{nil} stands for the default directory.
@code{load} tries all three possible suffixes in the first directory in
@code{load-path}, then all three suffixes in the second directory, and
so on.
so on. @xref{Library Search}.
If you get a warning that @file{foo.elc} is older than @file{foo.el}, it
means you should consider recompiling @file{foo.el}. @xref{Byte
@ -118,7 +126,7 @@ See below.
This command loads the file @var{filename}. If @var{filename} is a
relative file name, then the current default directory is assumed.
@code{load-path} is not used, and suffixes are not appended. Use this
command if you wish to specify the file to be loaded exactly.
command if you wish to specify precisely the file name to load.
@end deffn
@deffn Command load-library library
@ -126,17 +134,43 @@ This command loads the library named @var{library}. It is equivalent to
@code{load}, except in how it reads its argument interactively.
@end deffn
@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.
@end defvar
@defvar load-read-function
This variable specifies an alternate expression-reading function for
@code{load} and @code{eval-region} to use instead of @code{read}.
The function should accept one argument, just as @code{read} does.
Normally, the variable's value is @code{nil}, which means those
functions should use @code{read}.
@end defvar
For how @code{load} is used to build Emacs, see @ref{Building Emacs}.
@node Library Search
@section Library Search
When Emacs loads a Lisp library, it searches for the library
in a list of directories specified by the variable @code{load-path}.
@defopt load-path
@cindex @code{EMACSLOADPATH} environment variable
The value of this variable is a list of directories to search when
loading files with @code{load}. Each element is a string (which must be
a directory name) or @code{nil} (which stands for the current working
directory). The value of @code{load-path} is initialized from the
environment variable @code{EMACSLOADPATH}, if that exists; otherwise its
default value is specified in @file{emacs/src/paths.h} when Emacs is
built.
directory).
@end defopt
The syntax of @code{EMACSLOADPATH} is the same as used for @code{PATH};
The value of @code{load-path} is initialized from the environment
variable @code{EMACSLOADPATH}, if that exists; otherwise its default
value is specified in @file{emacs/src/paths.h} when Emacs is built.
Then the list is expanded by adding subdirectories of the directories
in the list.
The syntax of @code{EMACSLOADPATH} is the same as used for @code{PATH};
@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
@ -144,17 +178,17 @@ a @code{csh} @file{.login} file:
@c This overfull hbox is OK. --rjc 16mar92
@smallexample
setenv EMACSLOADPATH .:/user/bil/emacs:/usr/lib/emacs/lisp
setenv EMACSLOADPATH .:/user/bil/emacs:/usr/local/lib/emacs/lisp
@end smallexample
Here is how to set it using @code{sh}:
Here is how to set it using @code{sh}:
@smallexample
export EMACSLOADPATH
EMACSLOADPATH=.:/user/bil/emacs:/usr/local/lib/emacs/lisp
@end smallexample
Here is an example of code you can place in a @file{.emacs} file to add
Here is an example of code you can place in a @file{.emacs} file to add
several directories to the front of your default @code{load-path}:
@smallexample
@ -174,34 +208,37 @@ followed then by the @file{/user/bil/emacs} directory, the
@file{/usr/local/lisplib} directory, and the @file{~/emacs} directory,
which are then followed by the standard directories for Lisp code.
Dumping Emacs uses a special value of @code{load-path}. If the value of
Dumping Emacs uses a special value of @code{load-path}. If the value of
@code{load-path} at the end of dumping is unchanged (that is, still the
same special value), the dumped Emacs switches to the ordinary
@code{load-path} value when it starts up, as described above. But if
@code{load-path} has any other value at the end of dumping, that value
is used for execution of the dumped Emacs also.
Therefore, if you want to change @code{load-path} temporarily for
Therefore, if you want to change @code{load-path} temporarily for
loading a few libraries in @file{site-init.el} or @file{site-load.el},
you should bind @code{load-path} locally with @code{let} around the
calls to @code{load}.
@end defopt
The default value of @code{load-path}, when running an Emacs which has
been installed on the system, looks like this:
been installed on the system, includes two special directories (and
their subdirectories as well):
@smallexample
("/usr/local/share/emacs/@var{version}/site-lisp"
"/usr/local/share/emacs/site-lisp"
"/usr/local/share/emacs/@var{version}/lisp")
"/usr/local/share/emacs/@var{version}/site-lisp"
@end smallexample
The last of these three directories is where the Lisp files of Emacs
itself are installed; the first two are for additional Lisp packages
installed at your site. The first directory is for locally installed
packages that belong with a particular Emacs version; the second is for
locally installed packages that can be used with any installed Emacs
version.
@noindent
and
@smallexample
"/usr/local/share/emacs/site-lisp"
@end smallexample
@noindent
The first one is for locally installed packages for a particular Emacs
version; the second is for locally installed packages meant for use with
all installed Emacs versions.
There are several reasons why a Lisp package that works well in one
Emacs version can cause trouble in another. Sometimes packages need
@ -210,28 +247,23 @@ undocumented internal Emacs data that can change without notice;
sometimes a newer Emacs version incorporates a version of the package,
and should be used only with that version.
Emacs finds these directories' subdirectories and adds them to
@code{load-path} when it starts up. Both immediate subdirectories and
subdirectories multiple levels down are added to @code{load-path}.
Not all subdirectories are included, though. Subdirectories whose
names do not start with a letter or digit are excluded. Subdirectories
named @file{RCS} are excluded. Also, a subdirectory which contains a
file named @file{.nosearch} is excluded. You can use these methods to
prevent certain subdirectories of the @file{site-lisp} directories from
being searched.
If you run Emacs from the directory where it was built---that is, an
executable that has not been formally installed---then @code{load-path}
normally contains two additional directories. These are the @code{lisp}
and @code{site-lisp} subdirectories of the main build directory. (Both
are represented as absolute file names.)
@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.
@end defvar
@defvar load-read-function
This variable specifies an alternate expression-reading function for
@code{load} and @code{eval-region} to use instead of @code{read}.
The function should accept one argument, just as @code{read} does.
Normally, the variable's value is @code{nil}, which means those
functions should use @code{read}.
@end defvar
For how @code{load} is used to build Emacs, see @ref{Building Emacs}.
@deffn Command locate-library library &optional nosuffix path interactive-call
This command finds the precise file name for library @var{library}. It
searches for the library in the same way @code{load} does, and the
@ -248,6 +280,44 @@ interactively, the argument @var{interactive-call} is @code{t}, and this
tells @code{locate-library} to display the file name in the echo area.
@end deffn
@node Loading Non-ASCII
@section Loading Non-ASCII Characters
When Emacs Lisp programs contain string constants with non-@sc{ASCII}
characters, these can be represented within Emacs either as unibyte
strings or as multibyte strings (@pxref{Text Representations}). Which
representation is used depends on how the file is read into Emacs. If
it is read with decoding into multibyte representation, the text of the
Lisp program will be multibyte text, and its string constants will be
multibyte strings. If a file containing Latin-1 characters (for
example) is read without decoding, the text of the program will be
unibyte text, and its string constants will be unibyte strings.
@xref{Coding Systems}.
To make the results more predictable, Emacs always performs decoding
into the multibyte representation when loading Lisp files, even if it
was started with the @samp{--unibyte} option. This means that string
constants with non-@sc{ASCII} characters translate into multibyte
strings. The only exception is when a particular file specifies no
decoding.
The reason Emacs is designed this way is so that Lisp programs give
predictable results, regardless of how Emacs was started. In addition,
this enables programs that depend on using multibyte text to work even
in a unibyte Emacs. Of course, such programs should be designed to
notice whether the user prefers unibyte or multibyte text, by checking
@code{default-enable-multibyte-characters}, and convert representations
appropriately.
In most Emacs Lisp programs, the fact that non-@sc{ASCII} strings are
multibyte strings should not be noticeable, since inserting them in
unibyte buffers converts them to unibyte automatically. However, if
this does make a difference, you can force a particular Lisp file to be
interpreted as unibyte by writing @samp{-*-coding: raw-text;-*-} in a
comment on the file's first line. With that designator, the file will
be unconditionally be interpreted as unibyte, even in an ordinary
multibyte Emacs session.
@node Autoload
@section Autoload
@cindex autoload
@ -263,8 +333,8 @@ as if it had been loaded all along.
source before the real definition. @code{autoload} is the low-level
primitive for autoloading; any Lisp program can call @code{autoload} at
any time. Magic comments are the most convenient way to make a function
autoload, for packages installed along with Emacs. They do nothing on
their own, but they serve as a guide for the command
autoload, for packages installed along with Emacs. These comments do
nothing on their own, but they serve as a guide for the command
@code{update-file-autoloads}, which constructs calls to @code{autoload}
and arranges to execute them when Emacs is built.
@ -286,10 +356,10 @@ documentation without loading the function's real definition.
If @var{interactive} is non-@code{nil}, that says @var{function} can be
called interactively. This lets completion in @kbd{M-x} work without
loading its real definition. The complete interactive specification is
not given here; it's not needed unless the user actually calls
@var{function}, and when that happens, it's time to load the real
definition.
loading @var{function}'s real definition. The complete interactive
specification is not given here; it's not needed unless the user
actually calls @var{function}, and when that happens, it's time to load
the real definition.
You can autoload macros and keymaps as well as ordinary functions.
Specify @var{type} as @code{macro} if @var{function} is really a macro.
@ -338,9 +408,9 @@ or provide one or more features. If the file is not completely loaded
definitions or @code{provide} calls that occurred during the load are
undone. This is to ensure that the next attempt to call any function
autoloading from this file will try again to load the file. If not for
this, then some of the functions in the file might appear defined, but
they might fail to work properly for the lack of certain subroutines
defined later in the file and not loaded successfully.
this, then some of the functions in the file might be defined by the
aborted load, but fail to work properly for the lack of certain
subroutines not loaded successfully because they come later in the file.
If the autoloaded file fails to define the desired Lisp function or
macro, then an error is signaled with data @code{"Autoloading failed to
@ -348,7 +418,7 @@ define function @var{function-name}"}.
@findex update-file-autoloads
@findex update-directory-autoloads
A magic autoload comment looks like @samp{;;;###autoload}, on a line
A magic autoload comment consists of @samp{;;;###autoload}, on a line
by itself, just before the real definition of the function in its
autoloadable source file. The command @kbd{M-x update-file-autoloads}
writes a corresponding @code{autoload} call into @file{loaddefs.el}.
@ -398,7 +468,7 @@ documentation string in the @file{etc/DOC} file. @xref{Building Emacs}.
@section Repeated Loading
@cindex repeated loading
You can load one file more than once in an Emacs session. For
You can load a given file more than once in an Emacs session. For
example, after you have rewritten and reinstalled a function definition
by editing it in a buffer, you may wish to return to the original
version; you can do this by reloading the file it came from.
@ -409,7 +479,7 @@ rather than a non-compiled file of similar name. If you rewrite a file
that you intend to save and reinstall, you need to byte-compile the new
version; otherwise Emacs will load the older, byte-compiled file instead
of your newer, non-compiled file! If that happens, the message
displayed when loading the file includes, @samp{(compiled; source is
displayed when loading the file includes, @samp{(compiled; note, source is
newer)}, to remind you to recompile it.
When writing the forms in a Lisp library file, keep in mind that the
@ -435,7 +505,7 @@ 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}
To add an element to a list just once, you can also use @code{add-to-list}
(@pxref{Setting Variables}).
Occasionally you will want to test explicitly whether a library has

4
lispref/macros.texi
View file

@ -503,7 +503,7 @@ in expressions ordinarily.
@node Eval During Expansion
@subsection Evaluating Macro Arguments in Expansion
Another problem can happen if you the macro definition itself
Another problem can happen if the macro definition itself
evaluates any of the macro argument expressions, such as by calling
@code{eval} (@pxref{Eval}). If the argument is supposed to refer to the
user's variables, you may have trouble if the user happens to use a
@ -542,7 +542,7 @@ with @code{eval}) don't occur and its local variable bindings don't
exist.
To avoid these problems, @strong{don't evaluate an argument expression
while computing the macro expansion.} Instead, substitute the
while computing the macro expansion}. Instead, substitute the
expression into the macro expansion, so that its value will be computed
as part of executing the expansion. This is how the other examples in
this chapter work.

2
lispref/maps.texi
View file

@ -150,8 +150,8 @@ The keymap which displays the Files menu in the menu bar.
@vindex menu-bar-help-menu
The keymap which displays the Help menu in the menu bar.
@tindex menu-bar-mule-menu
@item menu-bar-mule-menu
@tindex menu-bar-mule-menu
@vindex menu-bar-mule-menu
The keymap which displays the Mule menu in the menu bar.

48
lispref/markers.texi
View file

@ -131,8 +131,8 @@ This function returns @code{t} if @var{object} is an integer or a marker,
@end defun
@defun number-or-marker-p object
This function returns @code{t} if @var{object} is a number (either kind)
or a marker, @code{nil} otherwise.
This function returns @code{t} if @var{object} is a number (either
integer or floating point) or a marker, @code{nil} otherwise.
@end defun
@node Creating Markers
@ -144,7 +144,7 @@ accessible portion of the buffer, or to the same place as another given
marker.
@defun make-marker
This functions returns a newly created marker that does not point
This function returns a newly created marker that does not point
anywhere.
@example
@ -216,8 +216,25 @@ passed an integer argument greater than the length of the buffer,
@code{copy-marker} returns a new marker that points to the end of the
buffer.
@example
@group
(copy-marker 0)
@result{} #<marker at 1 in markers.texi>
@end group
@group
(copy-marker 20000)
@result{} #<marker at 7572 in markers.texi>
@end group
@end example
An error is signaled if @var{marker} is neither a marker nor an
integer.
@end defun
Two distinct markers are considered @code{equal} (even though not
@code{eq}) to each other if they have the same position and buffer, or
if they both point nowhere.
@example
@group
@ -239,18 +256,7 @@ integer.
(equal p q)
@result{} t
@end group
@group
(copy-marker 0)
@result{} #<marker at 1 in markers.texi>
@end group
@group
(copy-marker 20000)
@result{} #<marker at 7572 in markers.texi>
@end group
@end example
@end defun
@node Information from Markers
@section Information from Markers
@ -296,10 +302,6 @@ This function returns the buffer that @var{marker} points into, or
@end example
@end defun
Two distinct markers are considered @code{equal} (even though not
@code{eq}) to each other if they have the same position and buffer, or
if they both point nowhere.
@node Marker Insertion Types
@section Marker Insertion Types
@ -311,16 +313,16 @@ marker should do by setting its @dfn{insertion type}. Note that use of
@code{insert-before-markers} ignores markers' insertion types, always
relocating a marker to point after the inserted text.
@tindex set-marker-insertion-type
@defun set-marker-insertion-type marker type
@tindex set-marker-insertion-type
This function sets the insertion type of marker @var{marker} to
@var{type}. If @var{type} is @code{t}, @var{marker} will advances when
text is inserted at it. If @var{type} is @code{nil}, @var{marker} does
not advance when text is inserted there.
@end defun
@tindex marker-insertion-type
@defun marker-insertion-type marker
@tindex marker-insertion-type
This function reports the current insertion type of @var{marker}.
@end defun
@ -377,9 +379,9 @@ This is another name for @code{set-marker}.
One special marker in each buffer is designated @dfn{the mark}. It
records a position for the user for the sake of commands such as
@kbd{C-w} and @kbd{C-x @key{TAB}}. Lisp programs should set the mark
only to values that have a potential use to the user, and never for
their own internal purposes. For example, the @code{replace-regexp}
@code{kill-region} and @code{indent-rigidly}. Lisp programs should set
the mark only to values that have a potential use to the user, and never
for their own internal purposes. For example, the @code{replace-regexp}
command sets the mark to the value of point before doing any
replacements, because this enables the user to move back there
conveniently after the replace is finished.

34
lispref/minibuf.texi
View file

@ -90,8 +90,8 @@ 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}.
reading the arguments for a command, in the @code{interactive}
specification. @xref{Defining Commands}.
@defun read-from-minibuffer prompt-string &optional initial-contents keymap read hist default inherit-input-method
This function is the most general way to get input through the
@ -115,7 +115,7 @@ The argument @var{default} specifies a default value to make available
through the history commands. It should be a string, or @code{nil}. If
@var{read} is non-@code{nil}, then @var{default} is also used as the
input to @code{read}, if the user enters empty input. However, in the
usual case (where @var{read} is @code{nil}, @code{read-from-minibuffer}
usual case (where @var{read} is @code{nil}), @code{read-from-minibuffer}
does not return @var{default} when the user enters empty input; it
returns an empty string, @code{""}. In this respect, it is different
from all the other minibuffer input functions in this chapter.
@ -136,9 +136,10 @@ properties were present in the minibuffer. Otherwise all the text
properties are stripped when the value is returned.
If the argument @var{inherit-input-method} is non-@code{nil}, then the
minibuffer inherits the current input method and the setting of
@code{enable-multibyte-characters} from whichever buffer was current
before entering the minibuffer.
minibuffer inherits the current buffer's input method (@pxref{Input
Methods}) and the setting of @code{enable-multibyte-characters}
(@pxref{Text Representations}) from whichever buffer was current before
entering the minibuffer.
If @var{initial-contents} is a string, @code{read-from-minibuffer}
inserts it into the minibuffer, leaving point at the end, before the
@ -425,7 +426,12 @@ arguments to other commands).
@end defvar
@defvar file-name-history
A history list for file name arguments.
A history list for file-name arguments.
@end defvar
@defvar buffer-name-history
@tindex buffer-name-history
A history list for buffer-name arguments.
@end defvar
@defvar regexp-history
@ -673,10 +679,10 @@ edit the input, providing several commands to attempt completion.
In most cases, we recommend using @var{default}, and not @var{initial}.
If the argument @var{inherit-input-method} is non-@code{nil}, then the
minibuffer inherits the current input method and the setting of
@code{enable-multibyte-characters} from whichever buffer was current
before entering the minibuffer. @xref{Input Methods,,, emacs, The GNU
Emacs Manual}.
minibuffer inherits the current buffer's input method (@pxref{Input
Methods}) and the setting of @code{enable-multibyte-characters}
(@pxref{Text Representations}) from whichever buffer was current before
entering the minibuffer.
Completion ignores case when comparing the input against the possible
matches, if the built-in variable @code{completion-ignore-case} is
@ -853,8 +859,8 @@ 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}.
reading the arguments for a command, in the @code{interactive}
specification. @xref{Defining Commands}.
@defun read-buffer prompt &optional default existing
This function reads the name of a buffer and returns it as a string.
@ -1412,8 +1418,8 @@ The return value of @code{map-y-or-n-p} is the number of objects acted on.
This function is useful for reading passwords.
@tindex read-password
@defun read-password prompt default
@tindex read-password
This function reads a password, echoing @samp{.} in the echo area
for each character entered, and returns it as a string. It prompts
with @var{prompt}, and returns @var{default} if the user enters the

81
lispref/modes.texi
View file

@ -305,7 +305,7 @@ the conventions listed above:
(if text-mode-map
() ; @r{Do not change the keymap if it is already set up.}
(setq text-mode-map (make-sparse-keymap))
(define-key text-mode-map "\t" 'tab-to-tab-stop)
(define-key text-mode-map "\t" 'indent-relative)
(define-key text-mode-map "\es" 'center-line)
(define-key text-mode-map "\eS" 'center-paragraph))
@end group
@ -399,7 +399,7 @@ mode functions:
(cond (lisp-syntax
(set-syntax-table lisp-mode-syntax-table)))
(setq local-abbrev-table lisp-mode-abbrev-table)
@dots{})
@dots{}
@end group
@end smallexample
@ -915,8 +915,8 @@ characters are reserved for major modes.)
minor mode; with it, you can specify all about a simple minor mode in
one self-contained definition.
@tindex easy-mmode-define-minor-mode
@defmac easy-mmode-define-minor-mode mode doc &optional init-value mode-indicator keymap
@tindex easy-mmode-define-minor-mode
This macro defines a new minor mode whose name is @var{mode} (a symbol).
This macro defines a command named @var{mode} which toggles the minor
@ -1144,12 +1144,11 @@ line. There is nothing inherently special about these variables; any
other variables could have the same effects on the mode line if
@code{mode-line-format} were changed to use them.
@tindex mode-line-mule-info
@defvar mode-line-mule-info
@tindex mode-line-mule-info
This variable holds the value of the mode-line construct that displays
information about the language environment, buffer coding system, and
current input method. @xref{International,,, emacs, The GNU Emacs
Manual}.
current input method. @xref{Non-ASCII Characters}.
@end defvar
@defvar mode-line-modified
@ -1165,8 +1164,8 @@ modified.
Changing this variable does not force an update of the mode line.
@end defvar
@tindex mode-line-frame-identification
@defvar mode-line-frame-identification
@tindex mode-line-frame-identification
This variable identifies the current frame. The default value is
@code{" "} if you are using a window system which can show multiple
frames, or @code{"-%F "} on an ordinary terminal which shows only one
@ -1426,6 +1425,7 @@ selected by the user, calls @var{function} with arguments
For Emacs Lisp mode, @var{pattern} could look like this:
@c should probably use imenu-syntax-alist and \\sw rather than [-A-Za-z0-9+]
@example
@group
((nil "^\\s-*(def\\(un\\|subst\\|macro\\|advice\\)\
@ -1437,7 +1437,8 @@ For Emacs Lisp mode, @var{pattern} could look like this:
@end group
@group
("*Types*"
"^\\s-*(def\\(type\\|struct\\|class\\|ine-condition\\)\
"^\\s-*\
(def\\(type\\|struct\\|class\\|ine-condition\\)\
\\s-+\\([-A-Za-z0-9+]+\\)" 2))
@end group
@end example
@ -1446,9 +1447,40 @@ Setting this variable makes it buffer-local in the current buffer.
@end defvar
@defvar imenu-case-fold-search
This variable controls whether the regular expression matching for Imenu
is case-sensitive: @code{t}, the default, means matching should ignore
case.
This variable controls whether matching against
@var{imenu-generic-expression} is case-sensitive: @code{t}, the default,
means matching should ignore case.
Setting this variable makes it buffer-local in the current buffer.
@end defvar
@defvar imenu-syntax-alist
This variable is an alist of syntax table modifiers to use while
executing @code{imenu--generic-function} to override the syntax table of
the current buffer. Each element should have this form:
@example
(@var{characters} . @var{syntax-description})
@end example
The @sc{car}, @var{characters}, can be either a character or a string.
The element says to give that character or characters the syntax
specified by @var{syntax-description}, which is passed to
@code{modify-syntax-entry} (@pxref{Syntax Table Functions}).
This feature is typically used to give word syntax to characters which
normally have symbol syntax, and thus to simplify
@code{imenu-generic-expression} and speed up matching.
For example, Fortran mode uses it this way:
@example
(setq imenu-syntax-alist '(("_$" . "w")))
@end example
The @code{imenu-generic-expression} patterns can then use @samp{\\sw+}
instead of @samp{\\(\\sw\\|\\s_\\)\\}. Note that this technique may be
inconvenient to use when the mode needs to limit the initial character
of a name to a smaller set of characters
Setting this variable makes it buffer-local in the current buffer.
@end defvar
@ -1568,7 +1600,7 @@ first symbol specifies how to do level 1 fontification, the second
symbol how to do level 2, and so on.
The second element, @var{keywords-only}, specifies the value of the
variable @code{font-lock-keywords-only}. If this is is non-@code{nil},
variable @code{font-lock-keywords-only}. If this is non-@code{nil},
syntactic fontification (of strings and comments) is not performed.
The third element, @var{case-fold}, specifies the value of
@ -1731,7 +1763,7 @@ where @var{submatcher} is much like @var{matcher}, with one
exception---see below. @var{pre-match-form} and @var{post-match-form}
are evaluated before the first, and after the last, instance
@var{anchored}'s @var{submatcher} is used. Therefore they can be used
to initialise before, and cleanup after, @var{submatcher} is used.
to initialize before, and cleanup after, @var{submatcher} is used.
Typically, @var{pre-match-form} is used to move to some position
relative to the original @var{submatcher}, before starting with
@var{anchored}'s @var{submatcher}. @var{post-match-form} might be used
@ -1787,7 +1819,7 @@ syntactically; it should only fontify based on
@end defvar
@ignore
Other variables include those for buffer-specialised fontification functions,
Other variables include those for buffer-specialized fontification functions,
`font-lock-fontify-buffer-function', `font-lock-unfontify-buffer-function',
`font-lock-fontify-region-function', `font-lock-unfontify-region-function',
`font-lock-inhibit-thing-lock' and `font-lock-maximum-size'.
@ -2039,6 +2071,27 @@ For example, here's how @code{emacs-lisp-mode} runs its mode hook:
@end example
@end defun
@defun run-hook-with-args hook &rest args
This function is the way to run an abnormal hook which passes arguments
to the hook functions. It calls each of the hook functions, passing
each of them the arguments @var{args}.
@end defun
@defun run-hook-with-args-until-failure hook &rest args
This function is the way to run an abnormal hook which passes arguments
to the hook functions, and stops as soon as any hook function fails. It
calls each of the hook functions, passing each of them the arguments
@var{args}, until some hook function returns @code{nil}. Then it stops.
@end defun
@defun run-hook-with-args-until-success hook &rest args
This function is the way to run an abnormal hook which passes arguments
to the hook functions, and stops as soon as any hook function succeeds.
It calls each of the hook functions, passing each of them the arguments
@var{args}, until some hook function returns non-@code{nil}. Then it
stops.
@end defun
@defun add-hook hook function &optional append local
This function is the handy way to add function @var{function} to hook
variable @var{hook}. The argument @var{function} may be any valid Lisp

830
lispref/nonascii.texi
View file

File diff suppressed because it is too large Load diff

43
lispref/numbers.texi
View file

@ -249,6 +249,11 @@ numbers or markers. However, it is a good idea to use @code{=} if you
can, even for comparing integers, just in case we change the
representation of integers in a future Emacs version.
Sometimes it is useful to compare numbers with @code{equal}; it treats
two numbers as equal if they have the same data type (both integers, or
both floating point) and the same value. By contrast, @code{=} can
treat an integer and a floating point number as equal.
There is another wrinkle: because floating point arithmetic is not
exact, it is often a bad idea to check for equality of two floating
point values. Usually it is better to test for approximate equality.
@ -328,7 +333,7 @@ This function returns the smallest of its arguments.
@end defun
@defun abs number
This returns the absolute value of @var{number}.
This function returns the absolute value of @var{number}.
@end defun
@node Numeric Conversions
@ -357,9 +362,9 @@ This returns @var{number}, converted to an integer by rounding downward
(towards negative infinity).
If @var{divisor} is specified, @var{number} is divided by @var{divisor}
before the floor is taken; this is the division operation that
corresponds to @code{mod}. An @code{arith-error} results if
@var{divisor} is 0.
before the floor is taken; this uses the kind of division operation that
corresponds to @code{mod}, rounding downward. An @code{arith-error}
results if @var{divisor} is 0.
@end defun
@defun ceiling number
@ -600,7 +605,7 @@ Conversions}.
@section Rounding Operations
@cindex rounding without conversion
The functions @code{ffloor}, @code{fceiling}, @code{fround} and
The functions @code{ffloor}, @code{fceiling}, @code{fround}, and
@code{ftruncate} take a floating point argument and return a floating
point result whose value is a nearby integer. @code{ffloor} returns the
nearest integer below; @code{fceiling}, the nearest integer above;
@ -965,14 +970,34 @@ and pi/2 (exclusive) whose tangent is @var{arg}.
@end defun
@defun exp arg
This is the exponential function; it returns @i{e} to the power
@var{arg}. @i{e} is a fundamental mathematical constant also called the
base of natural logarithms.
This is the exponential function; it returns
@tex
$e$
@end tex
@ifinfo
@i{e}
@end ifinfo
to the power @var{arg}.
@tex
$e$
@end tex
@ifinfo
@i{e}
@end ifinfo
is a fundamental mathematical constant also called the base of natural
logarithms.
@end defun
@defun log arg &optional base
This function returns the logarithm of @var{arg}, with base @var{base}.
If you don't specify @var{base}, the base @var{e} is used. If @var{arg}
If you don't specify @var{base}, the base
@tex
$e$
@end tex
@ifinfo
@i{e}
@end ifinfo
is used. If @var{arg}
is negative, the result is a NaN.
@end defun

75
lispref/objects.texi
View file

@ -396,8 +396,9 @@ distinction to the computer in any way.
@cindex alt characters
The X Window System defines three other modifier bits that can be set
in a character: @dfn{hyper}, @dfn{super} and @dfn{alt}. The syntaxes
for these bits are @samp{\H-}, @samp{\s-} and @samp{\A-}. Thus,
@samp{?\H-\M-\A-x} represents @kbd{Alt-Hyper-Meta-x}.
for these bits are @samp{\H-}, @samp{\s-} and @samp{\A-}. (Case is
significant in these prefixes.) Thus, @samp{?\H-\M-\A-x} represents
@kbd{Alt-Hyper-Meta-x}.
@tex
Numerically, the
bit values are $2^{22}$ for alt, $2^{23}$ for super and $2^{24}$ for hyper.
@ -882,9 +883,9 @@ character code, using a hex escape, @samp{\x@var{nnnnnnn}}, with as many
digits as necessary. (Multibyte non-@sc{ASCII} character codes are all
greater than 256.) Any character which is not a valid hex digit
terminates this construct. If the character that would follow is a hex
digit, write @samp{\ } to terminate the hex escape---for example,
@samp{\x8c0\ } represents one character, @samp{a} with grave accent.
@samp{\ } in a string constant is just like backslash-newline; it does
digit, write @w{@samp{\ }} to terminate the hex escape---for example,
@w{@samp{\x8c0\ }} represents one character, @samp{a} with grave accent.
@w{@samp{\ }} in a string constant is just like backslash-newline; it does
not contribute any character to the string, but it does terminate the
preceding hex escape.
@ -899,30 +900,35 @@ text representations.
@node Nonprinting Characters
@subsubsection Nonprinting Characters in Strings
Strings cannot hold characters that have the hyper, super, or alt
modifiers; the only control or meta characters they can hold are the
@sc{ASCII} control characters. Strings do not distinguish case in
@sc{ASCII} control characters.
You can use the same backslash escape-sequences in a string constant
as in character literals (but do not use the question mark that begins a
character constant). For example, you can write a string containing the
nonprinting characters tab, @kbd{C-a} and @kbd{M-C-a}, with commas and
spaces between them, like this: @code{"\t, \C-a, \M-\C-a"}.
@xref{Character Type}, for a description of the read syntax for
characters.
nonprinting characters tab and @kbd{C-a}, with commas and spaces between
them, like this: @code{"\t, \C-a"}. @xref{Character Type}, for a
description of the read syntax for characters.
If you use the @samp{\M-} syntax to indicate a meta character in a
string constant, this sets the
However, not all of the characters you can write with backslash
escape-sequences are valid in strings. The only control characters that
a string can hold are the @sc{ASCII} control characters. Strings do not
distinguish case in @sc{ASCII} control characters.
Properly speaking, strings cannot hold meta characters; but when a
string is to be used as a key sequence, there is a special convention
that allows the meta versions of @sc{ASCII} characters to be put in a
string. If you use the @samp{\M-} syntax to indicate a meta character
in a string constant, this sets the
@tex
$2^{7}$
@end tex
@ifinfo
2**7
@end ifinfo
bit of the character in the string. This construct works only with
ASCII characters. Note that the same meta characters have a different
representation when not in a string. @xref{Character Type}.
bit of the character in the string. If the string is used in
@code{define-key} or @code{lookup-key}, this numeric code is translated
into the equivalent meta character. @xref{Character Type}.
Strings cannot hold characters that have the hyper, super, or alt
modifiers.
@node Text Props and Strings
@subsubsection Text Properties in Strings
@ -960,7 +966,9 @@ represents a string whose textual contents are @samp{foo bar}, in which
the first three characters have a @code{face} property with value
@code{bold}, and the last three have a @code{face} property with value
@code{italic}. (The fourth character has no text properties so its
property list is @code{nil}.)
property list is @code{nil}. It is not actually necessary to mention
ranges with @code{nil} as the property list, since any characters not
mentioned in any range will default to having no properties.)
@node Vector Type
@subsection Vector Type
@ -1024,17 +1032,18 @@ that it begins with @samp{#&} followed by the length. The string
constant that follows actually specifies the contents of the bool-vector
as a bitmap---each ``character'' in the string contains 8 bits, which
specify the next 8 elements of the bool-vector (1 stands for @code{t},
and 0 for @code{nil}). If the length is not a multiple of 8, the
printed representation describes extra elements, but these really
make no difference.
and 0 for @code{nil}). The least significant bits of the character are
the lowest-numbered elements of the bool-vector. If the length is not a
multiple of 8, the printed representation shows extra elements, but
these extras really make no difference.
@example
(make-bool-vector 3 t)
@result{} #&3"\377"
@result{} #&3"\007"
(make-bool-vector 3 nil)
@result{} #&3"\0""
@result{} #&3"\0"
;; @r{These are equal since only the first 3 bits are used.}
(equal #&3"\377" #&3"\340")
(equal #&3"\377" #&3"\007")
@result{} t
@end example
@ -1151,7 +1160,7 @@ symbol. @xref{Autoload}, for more details.
@section Editing Types
@cindex editing types
The types in the previous section used for general programming
The types in the previous section are used for general programming
purposes, and most of them are common to most Lisp dialects. Emacs Lisp
provides several additional data types for purposes connected with
editing.
@ -1288,7 +1297,7 @@ in any given window can change frequently.
@node Frame Type
@subsection Frame Type
A @var{frame} is a rectangle on the screen that contains one or more
A @dfn{frame} is a rectangle on the screen that contains one or more
Emacs windows. A frame initially contains a single main window (plus
perhaps a minibuffer window) which you can subdivide vertically or
horizontally into smaller windows.
@ -1300,7 +1309,7 @@ uniquely).
@example
@group
(selected-frame)
@result{} #<frame emacs@@mole.gnu.ai.mit.edu 0xdac80>
@result{} #<frame emacs@@psilocin.gnu.org 0xdac80>
@end group
@end example
@ -1668,10 +1677,10 @@ object.
@end group
@end example
(The @code{make-symbol} function returns an uninterned symbol that is
not interned in the standard @code{obarray}. When uninterned symbols
are in use, symbol names are no longer unique. Distinct symbols with
the same name are not @code{eq}. @xref{Creating Symbols}.)
The @code{make-symbol} function returns an uninterned symbol, distinct
from the symbol that is used if you write the name in a Lisp expression.
Distinct symbols with the same name are not @code{eq}. @xref{Creating
Symbols}.
@example
@group

106
lispref/os.texi
View file

@ -54,6 +54,14 @@ can customize these actions.
it is started up is as follows:
@enumerate
@item
It adds subdirectories to @code{load-path}, by running the file
named @file{subdirs.el} in each directory that is listed.
@item
It sets the language environment and the terminal coding system,
if requested by environment variables such as @code{LANG}.
@item
It loads the initialization library for the window system, if you are
using a window system. This library's name is
@ -76,10 +84,9 @@ It loads the library @file{site-start}, unless the option
@cindex @file{site-start.el}
@item
It loads the file @file{~/.emacs}, unless @samp{-q} was specified on the
command line. (This is not done in @samp{-batch} mode.) The @samp{-u}
option can specify another user name whose home directory should be used
instead of @file{~}.
It loads the file @file{~/.emacs}, unless @samp{-q} or @samp{-batch} was
specified on the command line. The @samp{-u} option can specify another
user name whose home directory should be used instead of @file{~}.
@item
It loads the library @file{default}, unless @code{inhibit-default-init}
@ -146,10 +153,11 @@ form to your @file{.emacs} file:
"@var{your-login-name}")
@end example
Simply setting @code{inhibit-startup-echo-area-message} to your login
name is not sufficient to inhibit the message; Emacs explicitly checks
whether @file{.emacs} contains an expression as shown above. Your login
name must appear in the expression as a Lisp string constant.
Emacs explicitly checks for an expression as shown above in your
@file{.emacs} file; your login name must appear in the expression as a
Lisp string constant. Other methods of setting
@code{inhibit-startup-echo-area-message} to the same value do not
inhibit the startup message.
This way, you can easily inhibit the message for yourself if you wish,
but thoughtless copying of your @file{.emacs} file will not inhibit the
@ -206,9 +214,14 @@ then the default library is not loaded. The default value is
@end defopt
@defvar before-init-hook
@defvarx after-init-hook
These two normal hooks are run just before, and just after, loading of
the user's init file, @file{default.el}, and/or @file{site-start.el}.
This normal hook is run, once, just before loading of all the init files
(the user's init file, @file{default.el}, and/or @file{site-start.el}).
@end defvar
@defvar after-init-hook
This normal hook is run, once, just after loading of all the init files
(the user's init file, @file{default.el}, and/or @file{site-start.el}),
before the terminal-specific initialization.
@end defvar
@node Terminal-Specific
@ -216,18 +229,12 @@ the user's init file, @file{default.el}, and/or @file{site-start.el}.
@cindex terminal-specific initialization
Each terminal type can have its own Lisp library that Emacs loads when
run on that type of terminal. For a terminal type named @var{termtype},
the library is called @file{term/@var{termtype}}. Emacs finds the file
by searching the @code{load-path} directories as it does for other
files, and trying the @samp{.elc} and @samp{.el} suffixes. Normally,
terminal-specific Lisp library is located in @file{emacs/lisp/term}, a
subdirectory of the @file{emacs/lisp} directory in which most Emacs Lisp
libraries are kept.@refill
The library's name is constructed by concatenating the value of the
variable @code{term-file-prefix} and the terminal type. Normally,
@code{term-file-prefix} has the value @code{"term/"}; changing this
is not recommended.
run on that type of terminal. The library's name is constructed by
concatenating the value of the variable @code{term-file-prefix} and the
terminal type. Normally, @code{term-file-prefix} has the value
@code{"term/"}; changing this is not recommended. Emacs finds the file
in the normal manner, by searching the @code{load-path} directories, and
trying the @samp{.elc} and @samp{.el} suffixes.
The usual function of a terminal-specific library is to enable special
keys to send sequences that Emacs can recognize. It may also need to
@ -620,7 +627,7 @@ systems.
This function returns the name of the machine you are running on.
@example
(system-name)
@result{} "prep.ai.mit.edu"
@result{} "www.gnu.org"
@end example
@end defun
@ -719,19 +726,24 @@ locations, but can find them in a directory related somehow to the one
containing the Emacs executable.
@end defvar
@defun load-average
@defun load-average &optional use-float
This function returns the current 1-minute, 5-minute and 15-minute load
averages in a list. The values are integers that are 100 times the
system load averages, which indicate the average number of processes
trying to run. It would be more logical to use floating point numbers,
but this function was introduced before Emacs supported floating point
numbers, and it is not worth changing it now.
averages in a list.
By default, the values are integers that are 100 times the system load
averages, which indicate the average number of processes trying to run.
If @var{use-float} is non-@code{nil}, then they are returned
as floating point numbers instead.
@example
@group
(load-average)
@result{} (169 48 36)
@end group
@group
(load-average t)
@result{} (1.69 0.48 0.36)
@end group
@group
lewis@@rocky[5] % uptime
@ -745,8 +757,8 @@ lewis@@rocky[5] % uptime
This function returns the process @sc{id} of the Emacs process.
@end defun
@tindex tty-erase-char
@defvar tty-erase-char
@tindex tty-erase-char
This variable holds the erase character that was selected
in the system's terminal driver, before Emacs was started.
@end defvar
@ -859,7 +871,7 @@ This function returns the effective @sc{uid} of the user.
zone.
@defun current-time-string &optional time-value
This function returns the current time and date as a humanly-readable
This function returns the current time and date as a human-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. It is wise to count the
@ -1027,7 +1039,8 @@ This stands for the time zone abbreviation.
You can also specify the field width and type of padding for any of
these @samp{%}-sequences. This works as in @code{printf}: you write
the field width as digits in the middle of a @samp{%}-sequences. If you
start the field width with 0, it means to pad with zeros.
start the field width with @samp{0}, it means to pad with zeros. If you
start the field width with @samp{_}, it means to pad with spaces.
For example, @samp{%S} specifies the number of seconds since the minute;
@samp{%03S} means to pad this with zeros to 3 positions, @samp{%_3S} to
@ -1101,6 +1114,9 @@ feature makes it possible to use the elements of a list returned by
You can perform simple date arithmetic by using out-of-range values for
the @var{sec}, @var{minute}, @var{hour}, @var{day}, and @var{month}
arguments; for example, day 0 means the day preceding the given month.
The operating system puts limits on the range of possible time values;
if you try to encode a time that is out of range, an error results.
@end defun
@node Timers
@ -1124,10 +1140,18 @@ later, and @var{args} are the arguments to give it when it is called.
The time @var{time} is specified as a string.
Absolute times may be specified in a wide variety of formats, and tries
to accept all common date formats. One valid format is
@samp{@var{hour}:@var{min}:@var{sec} @var{timezone}
@var{month}/@var{day}/@var{year}}, where all fields are numbers; the
format that @code{current-time-string} returns is also allowed.
to accept all common date formats. Valid formats include these two,
@example
@var{year}-@var{month}-@var{day} @var{hour}:@var{min}:@var{sec} @var{timezone}
@var{hour}:@var{min}:@var{sec} @var{timezone} @var{month}/@var{day}/@var{year}
@end example
@noindent
where in both examples all fields are numbers; the format that
@code{current-time-string} returns is also allowed, and many others
as well.
To specify a relative time, use numbers followed by units.
For example:
@ -1168,7 +1192,7 @@ the value of the last form in @var{body}. If, however, the execution of
executes all the @var{timeout-forms} and returns the value of the last
of them.
This macro works by set a timer to run after @var{seconds} seconds. If
This macro works by setting a timer to run after @var{seconds} seconds. If
@var{body} finishes before that time, it cancels the timer. If the
timer actually runs, it terminates execution of @var{body}, then
executes @var{timeout-forms}.
@ -1290,8 +1314,8 @@ is non-@code{nil} when Emacs is using interrupt-driven input. If
@code{nil}, Emacs is using @sc{cbreak} mode.
@item flow
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 effect when
unless @var{interrupt} is @code{nil}.
flow control for output to the terminal. This value is meaningful only
when @var{interrupt} is @code{nil}.
@item meta
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
@ -1365,7 +1389,7 @@ versa. (@xref{Flow Control} for more information on this subject.)
@end group
@group
(setq keyboard-translate-table
(make-char-table 'keyboard-translate-table nil)))
(make-char-table 'keyboard-translate-table nil))
@end group
@group
;; @r{Swap @kbd{C-s} and @kbd{C-\}.}

24
lispref/positions.texi
View file

@ -180,10 +180,13 @@ whether a given character is part of a word. @xref{Syntax Tables}.
@deffn Command forward-word count
This function moves point forward @var{count} words (or backward if
@var{count} is negative). Normally it returns @code{t}. If this motion
encounters the beginning or end of the buffer, or the limits of the
accessible portion when narrowing is in effect, point stops there
and the value is @code{nil}.
@var{count} is negative). More precisely, it keeps moving until it
moves across a word-constituent character and encounters a
word-separator character, then returns @code{t}.
If this motion encounters the beginning or end of the buffer, or the
limits of the accessible portion when narrowing is in effect, point
stops there and the value is @code{nil}.
In an interactive call, @var{count} is set to the numeric prefix
argument.
@ -450,7 +453,7 @@ Display}.
These functions scan text to determine where screen lines break, and
thus take time proportional to the distance scanned. If you intend to
use them heavily, Emacs provides caches which may improve the
performance of your code. @xref{Text Lines, cache-long-line-scans}.
performance of your code. @xref{Truncation, cache-long-line-scans}.
@defun vertical-motion count &optional window
@ -507,7 +510,7 @@ 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
the number of columns not being displayed at the left margin; most
callers get this from @code{window-hscroll}. Meanwhile,
callers get this by calling @code{window-hscroll}. Meanwhile,
@var{tab-offset} is the offset between column numbers on the screen and
column numbers in the buffer. This can be nonzero in a continuation
line, when the previous screen lines' widths do not add up to a multiple
@ -725,7 +728,7 @@ an abnormal exit via @code{throw} or error (@pxref{Nonlocal Exits}).
The @code{save-excursion} special form is the standard way to switch
buffers or move point within one part of a program and avoid affecting
the rest of the program. It is used more than 500 times in the Lisp
the rest of the program. It is used more than 4000 times in the Lisp
sources of Emacs.
@code{save-excursion} does not save the values of point and the mark for
@ -759,6 +762,11 @@ The value returned by @code{save-excursion} is the result of the last of
@end example
@end defspec
@strong{Warning:} Ordinary insertion of text adjacent to the saved
point value relocates the saved value, just as it relocates all markers.
Therefore, when the saved point value is restored, it normally comes
after the inserted text.
Although @code{save-excursion} saves the location of the mark, it does
not prevent functions which modify the buffer from setting
@code{deactivate-mark}, and thus causing the deactivation of the mark
@ -857,7 +865,7 @@ of inaccessible text before and after the accessible portion.
This method yields correct results if @var{body} does further narrowing.
However, @code{save-restriction} can become confused if the body widens
and then make changes outside the range of the saved narrowing. When
and then makes changes outside the range of the saved narrowing. When
this is what you want to do, @code{save-restriction} is not the right
tool for the job. Here is what you must use instead:

85
lispref/processes.texi
View file

@ -34,6 +34,7 @@ This function returns @code{t} if @var{object} is a process,
@menu
* Subprocess Creation:: Functions that start subprocesses.
* Shell Arguments:: Quoting an argument to pass it to a shell.
* Synchronous Processes:: Details of using synchronous subprocesses.
* Asynchronous Processes:: Starting up an asynchronous subprocess.
* Deleting Processes:: Eliminating an asynchronous subprocess.
@ -190,8 +191,6 @@ process terminated.
coding system, much like text read from a file. The input sent to a
subprocess by @code{call-process-region} is encoded using a coding
system, much like text written into a file. @xref{Coding Systems}.
On Microsoft operating systems, additional variables control
the conversion for end-of-line (@pxref{MS-DOS Subprocesses}).
@defun call-process program &optional infile destination display &rest args
This function calls @var{program} in a separate process and waits for
@ -240,9 +239,14 @@ buffer.
@end table
If @var{display} is non-@code{nil}, then @code{call-process} redisplays
the buffer as output is inserted. Otherwise the function does no
redisplay, and the results become visible on the screen only when Emacs
redisplays that buffer in the normal course of events.
the buffer as output is inserted. (However, if the coding system chosen
for decoding output is @code{undecided}, meaning deduce the encoding
from the actual data, then redisplay sometimes cannot continue once
non-@sc{ASCII} characters are encountered. There are fundamental
reasons why it is hard to fix this.) Otherwise the function
@code{call-process} does no redisplay, and the results become visible on
the screen only when Emacs redisplays that buffer in the normal course
of events.
The remaining arguments, @var{args}, are strings that specify command
line arguments for the program.
@ -351,8 +355,8 @@ inputinput@point{}
@end smallexample
@end defun
@tindex shell-command-to-string
@defun shell-command-to-string command
@tindex shell-command-to-string
This function executes @var{command} (a string) as a shell command,
then returns the command's output as a string.
@end defun
@ -362,10 +366,15 @@ then returns the command's output as a string.
@cindex asynchronous subprocess
After an @dfn{asynchronous process} is created, Emacs and the Lisp
program both continue running immediately. The process may thereafter
run in parallel with Emacs, and the two may communicate with each other
using the functions described in following sections. Here we describe
how to create an asynchronous process with @code{start-process}.
program both continue running immediately. The process thereafter runs
in parallel with Emacs, and the two can communicate with each other
using the functions described in following sections. However,
communication is only partially asynchronous: Emacs sends data to the
process only when certain functions are called, and Emacs accepts data
from the process only when Emacs is waiting for input or for a time
delay.
Here we describe how to create an asynchronous process.
@defun start-process name buffer-or-name program &rest args
This function creates a new asynchronous subprocess and starts the
@ -570,8 +579,8 @@ process is started and remains constant as long as the process exists.
This function returns the name of @var{process}.
@end defun
@tindex process-contact
@defun process-contact process
@tindex process-contact
This function returns @code{t} for an ordinary child process, and
@code{(@var{hostname} @var{service})} for a net connection
(@pxref{Network}).
@ -639,8 +648,8 @@ instead of a terminal (see @code{process-connection-type} in
@ref{Asynchronous Processes}).
@end defun
@tindex process-coding-system
@defun process-coding-system process
@tindex process-coding-system
This function returns a cons cell describing the coding systems in use
for decoding output from @var{process} and for encoding input to
@var{process} (@pxref{Coding Systems}). The value has this form:
@ -650,8 +659,8 @@ for decoding output from @var{process} and for encoding input to
@end example
@end defun
@tindex set-process-coding-system
@defun set-process-coding-system process decoding-system encoding-system
@tindex set-process-coding-system
This function specifies the coding systems to use for subsequent output
from and input to @var{process}. It will use @var{decoding-system} to
decode subprocess output, and @var{encoding-system} to encode subprocess
@ -673,8 +682,11 @@ the other characters, to force them through. For most programs,
these @sc{eof}s do no harm.
Subprocess input is normally encoded using a coding system before the
subprocess receives it, much like text written into a file.
@xref{Coding Systems}.
subprocess receives it, much like text written into a file. You can use
@code{set-process-coding-system} to specify which coding system to use
(@pxref{Process Information}). Otherwise, the coding system comes from
@code{coding-system-for-write}, if that is non-@code{nil}; or else from
the defaulting mechanism (@pxref{Default Coding Systems}).
@defun process-send-string process-name string
This function sends @var{process-name} the contents of @var{string} as
@ -838,9 +850,32 @@ called the @dfn{filter function} can be called to act on the output. If
the process has no buffer and no filter function, its output is
discarded.
Output from a subprocess can arrive only while Emacs is waiting: when
reading terminal input, in @code{sit-for} and @code{sleep-for}
(@pxref{Waiting}), and in @code{accept-process-output} (@pxref{Accepting
Output}). This minimizes the problem of timing errors that usually
plague parallel programming. For example, you can safely create a
process and only then specify its buffer or filter function; no output
can arrive before you finish, if the code in between does not call any
primitive that waits.
Subprocess output is normally decoded using a coding system before the
buffer or filter function receives it, much like text read from a file.
@xref{Coding Systems}.
You can use @code{set-process-coding-system} to specify which coding
system to use (@pxref{Process Information}). Otherwise, the coding
system comes from @code{coding-system-for-read}, if that is
non-@code{nil}; or else from the defaulting mechanism (@pxref{Default
Coding Systems}).
@strong{Warning:} Coding systems such as @code{undecided} which
determine the coding system from the data do not work entirely reliably
with asynchronous subprocess output. This is because Emacs has to
process asynchronous subprocess output in batches, as it arrives. Emacs
must try to detect the proper coding system from one batch at a time,
and this does not always work. Therefore, if at all possible, use a
coding system which determines both the character code conversion and
the end of line conversion---that is, one like @code{latin-1-unix},
rather than @code{undecided} or @code{latin-1}.
@menu
* Process Buffers:: If no filter, output is put in a buffer.
@ -934,19 +969,16 @@ then @emph{all} output from that process is passed to the filter. The
process buffer is used directly for output from the process only when
there is no filter.
The filter function can only be called when Emacs is waiting for
something, because process output arrives only at such times. Emacs
waits when reading terminal input, in @code{sit-for} and
@code{sleep-for} (@pxref{Waiting}), and in @code{accept-process-output}
(@pxref{Accepting Output}).
A filter function must accept two arguments: the associated process
and a string, which is output just received from it. The function is
then free to do whatever it chooses with the output.
A filter function runs only while Emacs is waiting (e.g., for terminal
input, or for time to elapse, or for process output). This avoids the
timing errors that could result from running filters at random places in
the middle of other Lisp programs. You may explicitly cause Emacs to
wait, so that filter functions will run, by calling @code{sit-for} or
@code{sleep-for} (@pxref{Waiting}), or @code{accept-process-output}
(@pxref{Accepting Output}). Emacs is also waiting when the command loop
is reading input.
Quitting is normally inhibited within a filter function---otherwise,
the effect of typing @kbd{C-g} at command level or to quit a user
command would be unpredictable. If you want to permit quitting inside a
@ -1161,7 +1193,8 @@ errors that could result from running them at random places in the
middle of other Lisp programs. A program can wait, so that sentinels
will run, by calling @code{sit-for} or @code{sleep-for}
(@pxref{Waiting}), or @code{accept-process-output} (@pxref{Accepting
Output}). Emacs is also waiting when the command loop is reading input.
Output}). Emacs also allows sentinels to run when the command loop is
reading input.
Quitting is normally inhibited within a sentinel---otherwise, the
effect of typing @kbd{C-g} at command level or to quit a user command

35
lispref/searching.texi
View file

@ -231,11 +231,12 @@ this choice, the rest of the regexp matches successfully.@refill
Nested repetition operators can be extremely slow if they specify
backtracking loops. For example, it could take hours for the regular
expression @samp{\(x+y*\)*a} to match the sequence
@samp{xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxz}. The slowness is because
Emacs must try each imaginable way of grouping the 35 @samp{x}'s before
concluding that none of them can work. To make sure your regular
expressions run fast, check nested repetitions carefully.
expression @samp{\(x+y*\)*a} to try to match the sequence
@samp{xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxz}, before it ultimately fails.
The slowness is because Emacs must try each imaginable way of grouping
the 35 @samp{x}'s before concluding that none of them can work. To make
sure your regular expressions run fast, check nested repetitions
carefully.
@item @samp{+}
@cindex @samp{+} in regexp
@ -281,7 +282,7 @@ representations, because only the @sc{ASCII} characters are excluded.
The beginning and end of a range must be in the same character set
(@pxref{Character Sets}). Thus, @samp{[a-\x8c0]} is invalid because
@samp{a} is in the @sc{ASCII} character set but the character 0x8c0
(@samp{a} with grave accent) is in the Latin-1 character set.
(@samp{A} with grave accent) is in the Emacs character set for Latin-1.
Note that the usual regexp special characters are not special inside a
character alternative. A completely different set of characters are
@ -354,11 +355,11 @@ ordinary since there is no preceding expression on which the @samp{*}
can act. It is poor practice to depend on this behavior; quote the
special character anyway, regardless of where it appears.@refill
For the most part, @samp{\} followed by any character matches only
that character. However, there are several exceptions: two-character
sequences starting with @samp{\} which have special meanings. The
second character in the sequence is always an ordinary character on
their own. Here is a table of @samp{\} constructs.
For the most part, @samp{\} followed by any character matches only that
character. However, there are several exceptions: two-character
sequences starting with @samp{\} which have special meanings. (The
second character in such a sequence is always ordinary when used on its
own.) Here is a table of @samp{\} constructs.
@table @samp
@item \|
@ -393,8 +394,8 @@ or @samp{barx}.
@item
To enclose a complicated expression for the postfix operators @samp{*},
@samp{+} and @samp{?} to operate on. Thus, @samp{ba\(na\)*} matches
@samp{bananana}, etc., with any (zero or more) number of @samp{na}
strings.@refill
@samp{ba}, @samp{bana}, @samp{banana}, @samp{bananana}, etc., with any
number (zero or more) of @samp{na} strings.
@item
To record a matched substring for future reference.
@ -530,8 +531,8 @@ whitespace:
@end example
@end defun
@tindex regexp-opt
@defun regexp-opt strings &optional paren
@tindex regexp-opt
This function returns an efficient regular expression that will match
any of the strings @var{strings}. This is useful when you need to make
matching or searching as fast as possible---for example, for Font Lock
@ -555,8 +556,8 @@ regular expression which is equivalent to the actual value
@end example
@end defun
@tindex regexp-opt-depth
@defun regexp-opt-depth regexp
@tindex regexp-opt-depth
This function returns the total number of grouping constructs
(parenthesized expressions) in @var{regexp}.
@end defun
@ -1091,6 +1092,10 @@ subexpression is numbered 1, the second 2, and so on. Only regular
expressions can have subexpressions---after a simple string search, the
only information available is about the entire match.
A search which fails may or may not alter the match data. In the
past, a failing search did not do this, but we may change it in the
future.
@defun match-string count &optional in-string
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,

108
lispref/sequences.texi
View file

@ -82,7 +82,7 @@ This function returns the number of elements in @var{sequence}. If
@sc{cdr} is not @code{nil}), a @code{wrong-type-argument} error is
signaled.
@xref{List Elements}, for the related function @code{safe-list}.
@xref{List Elements}, for the related function @code{safe-length}.
@example
@group
@ -132,11 +132,11 @@ otherwise, they trigger an @code{args-out-of-range} error.
@end group
@group
(elt [1 2 3 4] 4)
@error{}Args out of range: [1 2 3 4], 4
@error{} Args out of range: [1 2 3 4], 4
@end group
@group
(elt [1 2 3 4] -1)
@error{}Args out of range: [1 2 3 4], -1
@error{} Args out of range: [1 2 3 4], -1
@end group
@end example
@ -218,12 +218,12 @@ be accessed in constant time. In contrast, an element of a list
requires access time that is proportional to the position of the element
in the list.
Emacs defines four types of array, both of which are one-dimensional:
@dfn{strings}, @dfn{vectors}, @dfn{bool-vectors} and @dfn{char-tables}.
A vector is a general array; its elements can be any Lisp objects. A
string is a specialized array; its elements must be characters (i.e.,
integers between 0 and 255). Each type of array has its own read
syntax. @xref{String Type}, and @ref{Vector Type}.
Emacs defines four types of array, all one-dimensional: @dfn{strings},
@dfn{vectors}, @dfn{bool-vectors} and @dfn{char-tables}. A vector is a
general array; its elements can be any Lisp objects. A string is a
specialized array; its elements must be characters (i.e., integers
between 0 and 255). Each type of array has its own read syntax.
@xref{String Type}, and @ref{Vector Type}.
All four kinds of array share these characteristics:
@ -347,8 +347,8 @@ If @var{array} is a string and @var{object} is not a character, a
@code{wrong-type-argument} error results. If @var{array} is a string
and @var{object} is character, but @var{object} does not use the same
number of bytes as the character currently stored in @code{(aref
@var{object} @var{index})}, that is also an error. @xref{Chars and
Bytes}.
@var{object} @var{index})}, that is also an error. @xref{Splitting
Characters}.
@end defun
@defun fillarray array object
@ -520,19 +520,25 @@ list with the same elements (@pxref{Building Lists}):
@node Char-Tables
@section Char-Tables
@cindex char-tables
@cindex extra slots of char-table
A char-table is much like a vector, except that it is indexed by
character codes. Any valid character code, without modifiers, can be
used as an index in a char-table. You can access a char-table's
elements with @code{aref} and @code{aset}, as with any array.
Char-tables are constants when evaluated.
elements with @code{aref} and @code{aset}, as with any array. In
addition, a char-table can have @dfn{extra slots} to hold additional
data not associated with particular character codes. Char-tables are
constants when evaluated.
@cindex extra slots of char-table
@cindex subtype of char-table
Each char-table has a @dfn{subtype} which is a symbol. In order to be
a valid subtype, a symbol must have a @code{char-table-extra-slots}
property which is an integer between 0 and 10. This integer specifies
the number of @dfn{extra slots} in the char-table.
Each char-table has a @dfn{subtype} which is a symbol. The subtype
has two purposes: to distinguish char-tables meant for different uses,
and to control the number of extra slots. For example, display tables
are char-tables with @code{display-table} as the subtype, and syntax
tables are char-tables with @code{syntax-table} as the subtype. A valid
subtype must have a @code{char-table-extra-slots} property which is an
integer between 0 and 10. This integer specifies the number of
@dfn{extra slots} in the char-table.
@cindex parent of char-table
A char-table can have a @dfn{parent}. which is another char-table. If
@ -547,8 +553,8 @@ specifies @code{nil}.
@code{(aref @var{char-table} @var{c})} returns the default value
whenever the char-table does not specify any other non-@code{nil} value.
@tindex make-char-table
@defun make-char-table subtype &optional init
@tindex make-char-table
Return a newly created char-table, with subtype @var{subtype}. Each
element is initialized to @var{init}, which defaults to @code{nil}. You
cannot alter the subtype of a char-table after the char-table is
@ -558,19 +564,19 @@ There is no argument to specify the length of the char-table, because
all char-tables have room for any valid character code as an index.
@end defun
@tindex char-table-p
@defun char-table-p object
@tindex char-table-p
This function returns @code{t} if @var{object} is a char-table,
otherwise @code{nil}.
@end defun
@tindex char-table-subtype
@defun char-table-subtype char-table
@tindex char-table-subtype
This function returns the subtype symbol of @var{char-table}.
@end defun
@tindex set-char-table-default
@defun set-char-table-default char-table new-default
@tindex set-char-table-default
This function sets the default value of @var{char-table} to
@var{new-default}.
@ -578,26 +584,26 @@ There is no special function to access the default value of a char-table.
To do that, use @code{(char-table-range @var{char-table} nil)}.
@end defun
@tindex char-table-parent
@defun char-table-parent char-table
@tindex char-table-parent
This function returns the parent of @var{char-table}. The parent is
always either @code{nil} or another char-table.
@end defun
@tindex set-char-table-parent
@defun set-char-table-parent char-table new-parent
@tindex set-char-table-parent
This function sets the parent of @var{char-table} to @var{new-parent}.
@end defun
@tindex char-table-extra-slot
@defun char-table-extra-slot char-table n
@tindex char-table-extra-slot
This function returns the contents of extra slot @var{n} of
@var{char-table}. The number of extra slots in a char-table is
determined by its subtype.
@end defun
@tindex set-char-table-extra-slot
@defun set-char-table-extra-slot char-table n value
@tindex set-char-table-extra-slot
This function stores @var{value} in extra slot @var{n} of
@var{char-table}.
@end defun
@ -605,28 +611,34 @@ This function stores @var{value} in extra slot @var{n} of
A char-table can specify an element value for a single character code;
it can also specify a value for an entire character set.
@tindex char-table-range
@defun char-table-range char-table range
@tindex char-table-range
This returns the value specified in @var{char-table} for a range of
characters @var{range}. Here @var{range} may be
characters @var{range}. Here are the possibilities for @var{range}:
@table @asis
@item @code{nil}
Refers to the default value.
@item @var{char}
Refers to the element for character @var{char}.
Refers to the element for character @var{char}
(supposing @var{char} is a valid character code).
@item @var{charset}
Refers to the value specified for the whole character set
@var{charset} (@pxref{Character Sets}).
@item @var{generic-char}
A generic character stands for a character set; specifying the generic
character as argument is equivalent to specifying the character set
name. @xref{Splitting Characters}, for a description of generic characters.
@end table
@end defun
@tindex set-char-table-range
@defun set-char-table-range char-table range value
@tindex set-char-table-range
This function set the value in @var{char-table} for a range of
characters @var{range}. Here @var{range} may be
characters @var{range}. Here are the possibilities for @var{range}:
@table @asis
@item @code{nil}
@ -636,24 +648,45 @@ Refers to the default value.
Refers to the whole range of character codes.
@item @var{char}
Refers to the element for character @var{char}.
Refers to the element for character @var{char}
(supposing @var{char} is a valid character code).
@item @var{charset}
Refers to the value specified for the whole character set
@var{charset} (@pxref{Character Sets}).
@item @var{generic-char}
A generic character stands for a character set; specifying the generic
character as argument is equivalent to specifying the character set
name. @xref{Splitting Characters}, for a description of generic characters.
@end table
@end defun
@tindex map-char-table
@defun map-char-table function char-table
@tindex map-char-table
This function calls @var{function} for each element of @var{char-table}.
@var{function} is called with two arguments, a key and a value. The key
is a possible @var{range} argument for @code{char-table-range}, and the
value is @code{(char-table-range @var{char-table} @var{key})}. Invalid
character codes are never used as @var{key}.
is a possible @var{range} argument for @code{char-table-range}---either
a valid character or a generic character---and the value is
@code{(char-table-range @var{char-table} @var{key})}.
Overall, the key-value pairs passed to @var{function} describe all the
values stored in @var{char-table}.
The return value is always @code{nil}; to make this function useful,
@var{function} should have side effects. For example,
here is how to examine each element of the syntax table:
@example
(map-char-table
#'(lambda (key value)
(setq accumulator
(cons (list key value) accumulator)))
(syntax-table))
@result{}
((475008 nil) (474880 nil) (474752 nil) (474624 nil)
... (5 (3)) (4 (3)) (3 (3)) (2 (3)) (1 (3)) (0 (3)))
@end example
@end defun
@node Bool-Vectors
@ -671,13 +704,14 @@ Bool-vectors are constants when evaluated.
from that, you manipulate them with same functions used for other kinds
of arrays.
@tindex make-bool-vector
@defun make-bool-vector length initial
@tindex make-bool-vector
Return a new book-vector of @var{length} elements,
each one initialized to @var{initial}.
@end defun
@defun bool-vector-p object
@tindex bool-vector-p
This returns @code{t} if @var{object} is a bool-vector,
and @code{nil} otherwise.
@end defun

38
lispref/streams.texi
View file

@ -255,7 +255,7 @@ useless-list
@end example
@noindent
Note that the open and close parentheses remains in the list. The Lisp
Note that the open and close parentheses remain in the list. The Lisp
reader encountered the open parenthesis, decided that it ended the
input, and unread it. Another attempt to read from the stream at this
point would read @samp{()} and return @code{nil}.
@ -353,14 +353,15 @@ Point advances as characters are inserted.
The output characters are inserted into the buffer that @var{marker}
points into, at the marker position. The marker position advances as
characters are inserted. The value of point in the buffer has no effect
on printing when the stream is a marker.
on printing when the stream is a marker, and this kind of printing
does not move point.
@item @var{function}
@cindex function output stream
The output characters are passed to @var{function}, which is responsible
for storing them away. It is called with a single character as
argument, as many times as there are characters to be output, and is
free to do anything at all with the characters it receives.
argument, as many times as there are characters to be output, and
is responsible for storing the characters wherever you want to put them.
@item @code{t}
@cindex @code{t} output stream
@ -368,9 +369,9 @@ The output characters are displayed in the echo area.
@item @code{nil}
@cindex @code{nil} output stream
@code{nil} specified as an output stream means to the value of
@code{nil} specified as an output stream means to use the value of
@code{standard-output} instead; that value is the @dfn{default output
stream}, and must be a non-@code{nil} output stream.
stream}, and must not be @code{nil}.
@item @var{symbol}
A symbol as output stream is equivalent to the symbol's function
@ -425,7 +426,7 @@ effect.
@example
@group
---------- Buffer: foo ----------
"This is the @point{}output"
This is the @point{}output
---------- Buffer: foo ----------
@end group
@ -441,9 +442,9 @@ m
@group
---------- Buffer: foo ----------
"This is t
This is t
"More output for foo."
he @point{}output"
he @point{}output
---------- Buffer: foo ----------
@end group
@ -535,12 +536,13 @@ describe a Lisp object clearly for a Lisp programmer. However, if the
purpose of the output is to look nice for humans, then it is usually
better to print without quoting.
Printing a self-referent Lisp object in the normal way would require
an infinite amount of text, and could even result in stack overflow.
Emacs detects such recursion and prints @samp{#@var{level}} instead of
recursively printing an object already being printed. For example, here
@samp{#0} indicates a recursive reference to the object at level 0 of
the current print operation:
Lisp objects can refer to themselves. Printing a self-referential
object in the normal way would require an infinite amount of text, and
the attempt could cause infinite recursion. Emacs detects such
recursion and prints @samp{#@var{level}} instead of recursively printing
an object already being printed. For example, here @samp{#0} indicates
a recursive reference to the object at level 0 of the current print
operation:
@example
(setq foo (list nil))
@ -661,10 +663,10 @@ See @code{format}, in @ref{String Conversion}, for other ways to obtain
the printed representation of a Lisp object as a string.
@end defun
@tindex with-output-to-string
@defmac with-output-to-string body...
This macro executes the @var{body} forms with standard-output set up so
that all output feeds into a string. Then it returns that string.
@tindex with-output-to-string
This macro executes the @var{body} forms with @code{standard-output} set
up to feed output into a string. Then it returns that string.
For example, if the current buffer name is @samp{foo},

93
lispref/strings.texi
View file

@ -28,7 +28,7 @@ keyboard character events.
* Modifying Strings:: Altering the contents of an existing string.
* Text Comparison:: Comparing characters or strings.
* String Conversion:: Converting characters or strings and vice versa.
* Formatting Strings:: @code{format}: Emacs's analog of @code{printf}.
* Formatting Strings:: @code{format}: Emacs's analogue of @code{printf}.
* Case Conversion:: Case conversion functions.
* Case Tables:: Customizing case conversion.
@end menu
@ -97,12 +97,12 @@ For more information about general sequence and array predicates,
see @ref{Sequences Arrays Vectors}, and @ref{Arrays}.
@defun stringp object
This function returns @code{t} if @var{object} is a string, @code{nil}
This function returns @code{t} if @var{object} is a string, @code{nil}
otherwise.
@end defun
@defun char-or-string-p object
This function returns @code{t} if @var{object} is a string or a
This function returns @code{t} if @var{object} is a string or a
character (i.e., an integer), @code{nil} otherwise.
@end defun
@ -113,7 +113,7 @@ character (i.e., an integer), @code{nil} otherwise.
putting strings together, or by taking them apart.
@defun make-string count character
This function returns a string made up of @var{count} repetitions of
This function returns a string made up of @var{count} repetitions of
@var{character}. If @var{count} is negative, an error is signaled.
@example
@ -128,8 +128,8 @@ putting strings together, or by taking them apart.
@code{make-list} (@pxref{Building Lists}).
@end defun
@tindex string
@defun string &rest characters
@tindex string
This returns a string containing the characters @var{characters}.
@example
@ -232,7 +232,7 @@ returns an empty string.
@example
(concat "abc" "-def")
@result{} "abc-def"
(concat "abc" (list 120 (+ 256 121)) [122])
(concat "abc" (list 120 121) [122])
@result{} "abcxyz"
;; @r{@code{nil} is an empty sequence.}
(concat "abc" nil "-def")
@ -244,10 +244,6 @@ returns an empty string.
@end example
@noindent
The second example above shows how characters stored in strings are
taken modulo 256. In other words, each character in the string is
stored in one byte.
The @code{concat} function always constructs a new string that is
not @code{eq} to any existing string.
@ -274,8 +270,8 @@ description of @code{mapconcat} in @ref{Mapping Functions},
Lists}.
@end defun
@tindex split-string
@defun split-string string separators
@tindex split-string
Split @var{string} into substrings in between matches for the regular
expression @var{separators}. Each match for @var{separators} defines a
splitting point; the substrings between the splitting points are made
@ -322,8 +318,8 @@ that index, @code{aset} signals an error.
A more powerful function is @code{store-substring}:
@tindex store-substring
@defun store-substring string idx obj
@tindex store-substring
This function alters part of the contents of the string @var{string}, by
storing @var{obj} starting at index @var{idx}. The argument @var{obj}
may be either a character or a (smaller) string.
@ -432,6 +428,41 @@ no characters is less than any other string.
@defun string-lessp string1 string2
@code{string-lessp} is another name for @code{string<}.
@end defun
@defun compare-strings string1 start1 end1 string2 start2 end2 &optional ignore-case
@tindex compare-strings
This function compares a specified part of @var{string1} with a
specified part of @var{string2}. The specified part of @var{string1}
runs from index @var{start1} up to index @var{end1} (default, the end of
the string). The specified part of @var{string2} runs from index
@var{start2} up to index @var{end2} (default, the end of the string).
The strings are both converted to multibyte for the comparison
(@pxref{Text Representations}) so that a unibyte string can be usefully
compared with a multibyte string. If @var{ignore-case} is
non-@code{nil}, then case is ignored as well.
If the specified portions of the two strings match, the value is
@code{t}. Otherwise, the value is an integer which indicates how many
leading characters agree, and which string is less. Its absolute value
is one plus the number of characters that agree at the beginning of the
two strings. The sign is negative if @var{string1} (or its specified
portion) is less.
@end defun
@defun assoc-ignore-case key alist
@tindex assoc-ignore-case
This function works like @code{assoc}, except that @var{key} must be a
string, and comparison is done using @code{compare-strings}.
Case differences are ignored in this comparison.
@end defun
@defun assoc-ignore-representation key alist
@tindex assoc-ignore-representation
This function works like @code{assoc}, except that @var{key} must be a
string, and comparison is done using @code{compare-strings}.
Case differences are significant.
@end defun
See also @code{compare-buffer-substrings} in @ref{Comparing Text}, for
@ -509,7 +540,7 @@ negative.
See also the function @code{format} in @ref{Formatting Strings}.
@end defun
@defun string-to-number string base
@defun string-to-number string &optional base
@cindex string to number
This function returns the numeric value of the characters in
@var{string}. If @var{base} is non-@code{nil}, integers are converted
@ -522,7 +553,7 @@ The parsing skips spaces and tabs at the beginning of @var{string}, then
reads as much of @var{string} as it can interpret as a number. (On some
systems it ignores other whitespace at the beginning, not just spaces
and tabs.) If the first character after the ignored whitespace is not a
digit or a minus sign, this function returns 0.
digit or a plus or minus sign, this function returns 0.
@example
(string-to-number "256")
@ -600,10 +631,9 @@ second such value, and so on. Any extra format specifications (those
for which there are no corresponding values) cause unpredictable
behavior. Any extra values to be formatted are ignored.
Certain format specifications require values of particular types.
However, no error is signaled if the value actually supplied fails to
have the expected type. Instead, the output is likely to be
meaningless.
Certain format specifications require values of particular types. If
you supply a value that doesn't fit the requirements, an error is
signaled.
Here is a table of valid format specifications:
@ -652,7 +682,7 @@ point number.
@item %g
Replace the specification with notation for a floating point number,
using either exponential notation or decimal-point notation whichever
using either exponential notation or decimal-point notation, whichever
is shorter.
@item %%
@ -741,10 +771,14 @@ not truncated. In the third case, the padding is on the right.
@cindex case conversion in Lisp
The character case functions change the case of single characters or
of the contents of strings. The functions convert only alphabetic
characters (the letters @samp{A} through @samp{Z} and @samp{a} through
@samp{z}); other characters are not altered. The functions do not
modify the strings that are passed to them as arguments.
of the contents of strings. The functions normally convert only
alphabetic characters (the letters @samp{A} through @samp{Z} and
@samp{a} through @samp{z}, as well as non-ASCII letters); other
characters are not altered. (You can specify a different case
conversion mapping by specifying a case table---@pxref{Case Tables}.)
These functions do not modify the strings that are passed to them as
arguments.
The examples below use the characters @samp{X} and @samp{x} which have
@sc{ASCII} codes 88 and 120 respectively.
@ -823,8 +857,8 @@ has the same result as @code{upcase}.
@defun upcase-initials string
This function capitalizes the initials of the words in @var{string}.
without altering any letters other than the initials. It returns a new
string whose contents are a copy of @var{string-or-char}, in which each
word has been converted to upper case.
string whose contents are a copy of @var{string}, in which each word has
been converted to upper case.
The definition of a word is any sequence of consecutive characters that
are assigned to the word constituent syntax class in the current syntax
@ -838,6 +872,9 @@ table (@xref{Syntax Class Table}).
@end example
@end defun
@xref{Text Comparison}, for functions that compare strings; some of
them ignore case differences, or can optionally ignore case differences.
@node Case Tables
@section The Case Table
@ -860,10 +897,10 @@ The upcase table maps each character into the corresponding upper
case character.
@item canonicalize
The canonicalize table maps all of a set of case-related characters
into some one of them.
into a particular member of that set.
@item equivalences
The equivalences table maps each of a set of case-related characters
into the next one in that set.
The equivalences table maps each one of a set of case-related characters
into the next character in that set.
@end table
In simple cases, all you need to specify is the mapping to lower-case;

12
lispref/symbols.texi
View file

@ -121,12 +121,12 @@ The property list cell contains the list @code{(variable-documentation
documentation string for the variable @code{buffer-file-name} in the
@file{DOC-@var{version}} file. (29529 is the offset from the beginning
of the @file{DOC-@var{version}} file to where that documentation string
begins---@pxref{Documentation Basics}) The function cell contains the
function for returning the name of the file. @code{buffer-file-name}
names a primitive function, which has no read syntax and prints in hash
notation (@pxref{Primitive Function Type}). A symbol naming a function
written in Lisp would have a lambda expression (or a byte-code object)
in this cell.
begins---see @ref{Documentation Basics}.) The function cell contains
the function for returning the name of the file.
@code{buffer-file-name} names a primitive function, which has no read
syntax and prints in hash notation (@pxref{Primitive Function Type}). A
symbol naming a function written in Lisp would have a lambda expression
(or a byte-code object) in this cell.
@node Definitions, Creating Symbols, Symbol Components, Symbols
@section Defining Symbols

34
lispref/syntax.texi
View file

@ -10,7 +10,7 @@
@cindex text parsing
A @dfn{syntax table} specifies the syntactic textual function of each
character. This information is used by the parsing commands, the
character. This information is used by the @dfn{parsing functions}, the
complex movement commands, and others to determine where words, symbols,
and other syntactic constructs begin and end. The current syntax table
controls the meaning of the word motion functions (@pxref{Word Motion})
@ -524,8 +524,8 @@ If the property is @code{nil}, the character's syntax is determined from
the current syntax table in the usual way.
@end table
@tindex parse-sexp-lookup-properties
@defvar parse-sexp-lookup-properties
@tindex parse-sexp-lookup-properties
If this is non-@code{nil}, the syntax scanning functions pay attention
to syntax text properties. Otherwise they use only the current syntax
table.
@ -765,43 +765,50 @@ a character to match was specified.
to each syntactic type.
@multitable @columnfractions .05 .3 .3 .3
@item@tab
@item
@tab
@i{Integer} @i{Class}
@tab
@i{Integer} @i{Class}
@tab
@i{Integer} @i{Class}
@item@tab
@item
@tab
0 @ @ whitespace
@tab
5 @ @ close parenthesis
@tab
10 @ @ character quote
@item@tab
@item
@tab
1 @ @ punctuation
@tab
6 @ @ expression prefix
@tab
11 @ @ comment-start
@item@tab
@item
@tab
2 @ @ word
@tab
7 @ @ string quote
@tab
12 @ @ comment-end
@item@tab
@item
@tab
3 @ @ symbol
@tab
8 @ @ paired delimiter
@tab
13 @ @ inherit
@item@tab
@item
@tab
4 @ @ open parenthesis
@tab
9 @ @ escape
@tab
14 @ @ comment-fence
@item@tab
@item
@tab
15 @ string-fence
@end multitable
@ -813,19 +820,22 @@ least significant bit. This table gives the power of two which
corresponds to each syntax flag.
@multitable @columnfractions .05 .3 .3 .3
@item@tab
@item
@tab
@i{Prefix} @i{Flag}
@tab
@i{Prefix} @i{Flag}
@tab
@i{Prefix} @i{Flag}
@item@tab
@item
@tab
@samp{1} @ @ @code{(lsh 1 16)}
@tab
@samp{3} @ @ @code{(lsh 1 18)}
@tab
@samp{p} @ @ @code{(lsh 1 20)}
@item@tab
@item
@tab
@samp{2} @ @ @code{(lsh 1 17)}
@tab
@samp{4} @ @ @code{(lsh 1 19)}

82
lispref/text.texi
View file

@ -196,8 +196,11 @@ properties, just the characters themselves. @xref{Text Properties}.
@defun buffer-string
This function returns the contents of the entire accessible portion of
the current buffer as a string. This is the portion between
@code{(point-min)} and @code{(point-max)} (@pxref{Narrowing}).
the current buffer as a string. It is equivalent to
@example
(buffer-substring (point-min) (point-max))
@end example
@example
@group
@ -302,6 +305,13 @@ 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.
The insertion functions convert text from unibyte to multibyte in
order to insert in a multibyte buffer, and vice versa---if the text
comes from a string or from a buffer. However, they do not convert
unibyte character codes 128 through 255 to multibyte characters, not
even if the current buffer is a multibyte buffer. @xref{Converting
Representations}.
@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
@ -328,6 +338,10 @@ current buffer before point. The argument @var{count} should be a
number (@code{nil} means 1), and @var{character} must be a character.
The value is @code{nil}.
This function does not convert unibyte character codes 128 through 255
to multibyte characters, not even if the current buffer is a multibyte
buffer. @xref{Converting Representations}.
If @var{inherit} is non-@code{nil}, then the inserted characters inherit
sticky text properties from the two characters before and after the
insertion point. @xref{Sticky Properties}.
@ -524,8 +538,8 @@ the kill ring.
The value returned is always @code{nil}.
@end deffn
@tindex backward-delete-char-untabify-method
@defopt backward-delete-char-untabify-method
@tindex backward-delete-char-untabify-method
This option specifies how @code{backward-delete-char-untabify} should
deal with whitespace. Possible values include @code{untabify}, the
default, meaning convert a tab to many spaces and delete one;
@ -579,7 +593,7 @@ This function joins the line point is on to the previous line, deleting
any whitespace at the join and in some cases replacing it with one
space. If @var{join-following-p} is non-@code{nil},
@code{delete-indentation} joins this line to the following line
instead. The value is @code{nil}.
instead. The function returns @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
@ -612,7 +626,7 @@ responsible for deciding whether to leave a space at the junction.
@end deffn
@defun fixup-whitespace
This function replaces all the white space surrounding point with either
This function replaces all the whitespace surrounding point with either
one space or no space, according to the context. It returns @code{nil}.
At the beginning or end of a line, the appropriate amount of space is
@ -728,9 +742,9 @@ new entry automatically deletes the last entry.
When kill commands are interwoven with other commands, each kill
command makes a new entry in the kill ring. Multiple kill commands in
succession build up a single entry in the kill ring, which would be
yanked as a unit; the second and subsequent consecutive kill commands
add text to the entry made by the first one.
succession build up a single kill-ring entry, which would be yanked as a
unit; the second and subsequent consecutive kill commands add text to
the entry made by the first one.
For yanking, one entry in the kill ring is designated the ``front'' of
the ring. Some yank commands ``rotate'' the ring by designating a
@ -825,7 +839,7 @@ The sequence of kills in the kill ring wraps around, so that after the
oldest one comes the newest one, and before the newest one goes the
oldest.
The value is always @code{nil}.
The return value is always @code{nil}.
@end deffn
@node Low-Level Kill Ring
@ -837,8 +851,8 @@ take care of interaction with window system selections
(@pxref{Window System Selections}).
@defun current-kill n &optional do-not-move
The function @code{current-kill} rotates the yanking pointer which
designates the ``front'' of the kill ring by @var{n} places (from newer
The function @code{current-kill} rotates the yanking pointer, which
designates the ``front'' of the kill ring, by @var{n} places (from newer
kills to older ones), and returns the text at that place in the ring.
If the optional second argument @var{do-not-move} is non-@code{nil},
@ -1049,8 +1063,8 @@ not make boundaries, and then the 20th does, and so on as long as
self-inserting characters continue.
All buffer modifications add a boundary whenever the previous undoable
change was made in some other buffer. This way, a command that modifies
several buffers makes a boundary in each buffer it changes.
change was made in some other buffer. This is to ensure that
each command makes a boundary in each buffer where it makes changes.
Calling this function explicitly is useful for splitting the effects of
a command into more than one unit. For example, @code{query-replace}
@ -1096,8 +1110,8 @@ In an interactive call, @var{buffer-or-name} is the current buffer.
You cannot specify any other buffer.
@end deffn
@defun buffer-disable-undo &optional buffer
@defunx buffer-flush-undo &optional buffer
@deffn Command buffer-disable-undo &optional buffer
@deffnx Command buffer-flush-undo &optional buffer
@cindex disable undo
This function discards the undo list of @var{buffer}, and disables
further recording of undo information. As a result, it is no longer
@ -1105,11 +1119,11 @@ possible to undo either previous changes or any subsequent changes. If
the undo list of @var{buffer} is already disabled, this function
has no effect.
This function returns @code{nil}. It cannot be called interactively.
This function returns @code{nil}.
The name @code{buffer-flush-undo} is not considered obsolete, but the
preferred name is @code{buffer-disable-undo}.
@end defun
@end deffn
As editing continues, undo lists get longer and longer. To prevent
them from using up all available memory space, garbage collection trims
@ -1214,6 +1228,7 @@ filling when @var{justify} is non-@code{nil}.
In an interactive call, any prefix argument requests justification.
@cindex Adaptive Fill mode
In Adaptive Fill mode, which is enabled by default, calling the function
@code{fill-region-as-paragraph} on an indented paragraph when there is
no fill prefix uses the indentation of the second line of the paragraph
@ -1279,7 +1294,8 @@ newlines'' act as paragraph separators.
@section Margins for Filling
@defopt fill-prefix
This variable specifies a string of text that appears at the beginning
This buffer-local variable specifies a string of text that appears at
the beginning
of normal text lines and should be disregarded when filling them. Any
line that fails to start with the fill prefix is considered the start of
a paragraph; so is any line that starts with the fill prefix followed by
@ -1290,7 +1306,7 @@ 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
@defvar fill-column
This buffer-local variable specifies the maximum width of filled lines.
Its value should be an integer, which is a number of columns. All the
filling, justification, and centering commands are affected by this
@ -1300,7 +1316,7 @@ As a practical matter, if you are writing text for other people to
read, you should set @code{fill-column} to no more than 70. Otherwise
the line will be too long for people to read comfortably, and this can
make the text seem clumsy.
@end defopt
@end defvar
@defvar default-fill-column
The value of this variable is the default value for @code{fill-column} in
@ -1367,8 +1383,8 @@ mode, @kbd{C-j} indents to this column. This variable automatically
becomes buffer-local when set in any fashion.
@end defvar
@tindex fill-nobreak-predicate
@defvar fill-nobreak-predicate
@tindex fill-nobreak-predicate
This variable gives major modes a way to specify not to break a line at
certain places. Its value should be a function. This function is
called during filling, with no arguments and with point located at the
@ -1787,8 +1803,8 @@ indent the current line in a way appropriate for the current major mode.
@deffn Command indent-for-tab-command
This command calls the function in @code{indent-line-function} to indent
the current line; except that if that function is
@code{indent-to-left-margin}, it calls @code{insert-tab} instead. (That
the current line; however, if that function is
@code{indent-to-left-margin}, @code{insert-tab} is called instead. (That
is a trivial command that inserts a tab character.)
@end deffn
@ -1842,7 +1858,8 @@ by making it start with the fill prefix.
@defvar indent-region-function
The value of this variable is a function that can be used by
@code{indent-region} as a short cut. You should design the function so
@code{indent-region} as a short cut. It should take two arguments, the
start and end of the region. You should design the function so
that it will produce the same results as indenting the lines of the
region one by one, but presumably faster.
@ -2389,16 +2406,16 @@ position less than or equal to @var{pos}; it equals @var{pos} only if
@var{limit} equals @var{pos}.
@end defun
@tindex next-char-property-change
@defun next-char-property-change position &optional limit
@tindex next-char-property-change
This is like @code{next-property-change} except that it considers
overlay properties as well as text properties. There is no @var{object}
operand because this function operates only on the current buffer. It
returns the next address at which either kind of property changes.
@end defun
@tindex previous-char-property-change
@defun previous-char-property-change position &optional limit
@tindex previous-char-property-change
This is like @code{next-char-property-change}, but scans back from
@var{position} instead of forward.
@end defun
@ -3160,17 +3177,14 @@ end of the region just changed, and the length of the text that existed
before the change. All three arguments are integers. The buffer that's
about to change is always the current buffer.
The length of the old text is measured in bytes; it is the difference
between the buffer positions before and after that text, before the
change. As for the changed text, its length in bytes is simply the
difference between the first two arguments. If you want the length
in @emph{characters} of the text before the change, you should use
a @code{before-change-functions} function that calls @code{chars-in-region}
(@pxref{Chars and Bytes}).
The length of the old text the difference between the buffer positions
before and after that text as it was before the change. As for the
changed text, its length is simply the difference between the first two
arguments.
@end defvar
@tindex combine-after-change-calls
@defmac combine-after-change-calls body...
@tindex combine-after-change-calls
The macro executes @var{body} normally, but arranges to call the
after-change functions just once for a series of several changes---if
that seems safe.

68
lispref/tips.texi
View file

@ -46,7 +46,7 @@ instead.
If you write a function that you think ought to be added to Emacs under
a certain name, such as @code{twiddle-files}, don't call it by that name
in your program. Call it @code{mylib-twiddle-files} in your program,
and send mail to @samp{bug-gnu-emacs@@prep.ai.mit.edu} suggesting we add
and send mail to @samp{bug-gnu-emacs@@gnu.org} suggesting we add
it to Emacs. If and when we do, we can change the name easily enough.
If one prefix is insufficient, your package may use two or three
@ -104,6 +104,8 @@ If a user option variable records a true-or-false condition, give it a
name that ends in @samp{-flag}.
@item
@cindex reserved keys
@cindex keys, reserved
Please do not define @kbd{C-c @var{letter}} as a key in your major
modes. These sequences are reserved for users; they are the
@strong{only} sequences reserved for users, so do not block them.
@ -262,7 +264,7 @@ Try to avoid compiler warnings about undefined free variables, by adding
If you bind a variable in one function, and use it or set it in another
function, the compiler warns about the latter function unless the
variable has a definition. But often these variables have short names,
and it is not clean for Lisp packages to define such variables names.
and it is not clean for Lisp packages to define such variable names.
Therefore, you should rename the variable to start with the name prefix
used for the other functions and variables in your package.
@ -317,8 +319,10 @@ Lisp programs.
@cindex profiling
@cindex timing programs
@cindex @file{profile.el}
Use the @file{profile} library to profile your program. See the file
@file{profile.el} for instructions.
@cindex @file{elp.el}
Profile your program with the @file{profile} library or the @file{elp}
library. See the files @file{profile.el} and @file{elp.el} for
instructions.
@item
Use iteration rather than recursion whenever possible.
@ -340,19 +344,13 @@ property. If the property is non-@code{nil}, then the function is
handled specially.
For example, the following input will show you that @code{aref} is
compiled specially (@pxref{Array Functions}) while @code{elt} is not
(@pxref{Sequence Functions}):
compiled specially (@pxref{Array Functions}):
@example
@group
(get 'aref 'byte-compile)
@result{} byte-compile-two-args
@end group
@group
(get 'elt 'byte-compile)
@result{} nil
@end group
@end example
@item
@ -480,14 +478,39 @@ t and nil without single-quotes. (In this manual, we use a different
convention, with single-quotes for all symbols.)
@end ifinfo
For example:
Help mode automatically creates hyperlinks when documentation strings
use symbol names inside single quotes, when the symbol has either a
function or a variable definition. You do not need to do anything
special to make use of this feature. However, when a symbol has both a
function definition and a variable definition, and you want to refer to
just one of them, you can specify which one by writing one of the words
@samp{variable}, @samp{option}, @samp{function}, or @samp{command},
immediately before the symbol name. (Case makes no difference in
recognizing these indicator words.) For example, if you write
@example
The value of `swim-speed' specifies how fast to swim.
Possible values are t for high speed, nil for low speed,
and `medium' for medium speed.
This function sets the variable `buffer-file-name'.
@end example
@noindent
then the hyperlink will refer only to the variable documentation of
@code{buffer-file-name}, and not to its function documentation.
If a symbol has a function definition and/or a variable definition, but
those are irrelevant to the use of the symbol that you are documenting,
you can write the word @samp{symbol} before the symbol name to prevent
making any hyperlink. For example,
@example
If the argument KIND-OF-RESULT is the symbol `list',
this function returns a list of all the objects
that satisfy the criterion.
@end example
@noindent
does not make a hyperlink to the documentation, irrelevant here, of the
function @code{list}.
@item
Don't write key sequences directly in documentation strings. Instead,
use the @samp{\\[@dots{}]} construct to stand for them. For example,
@ -692,6 +715,8 @@ example).
@item Keywords
This line lists keywords for the @code{finder-by-keyword} help command.
Please use that command to see a list of the meaningful keywords.
This field is important; it's how people will find your package when
they're looking for things by topic area. To separate the keywords, you
can use spaces, commas, or both.
@ -708,14 +733,21 @@ library file. Here is a table of them:
@table @samp
@item ;;; Commentary:
This begins introductory comments that explain how the library works.
It should come right after the copying permissions.
It should come right after the copying permissions, terminated by a
@samp{Change Log}, @samp{History} or @samp{Code} comment line. This
text is used by the Finder package, so it should make sense in that
context.
@item ;;; Change log:
@item ;;; Documentation
This has been used in some files in place of @samp{;;; Commentary:},
but @samp{;;; Commentary:} is preferred.
@item ;;; Change Log:
This begins change log information stored in the library file (if you
store the change history there). For most of the Lisp
files distributed with Emacs, the change history is kept in the file
@file{ChangeLog} and not in the source file at all; these files do
not have a @samp{;;; Change log:} line.
not have a @samp{;;; Change Log:} line.
@item ;;; Code:
This begins the actual code of the program.

83
lispref/variables.texi
View file

@ -104,7 +104,7 @@ include @code{nil} and @code{t}, as well as any symbol whose name starts
with @samp{:}. These symbols cannot be rebound, nor can their values be
changed. Any attempt to set or bind @code{nil} or @code{t} signals a
@code{setting-constant} error. The same is true for a symbol whose name
starts with @samp{:}, except that you are allowed to set such symbol to
starts with @samp{:}, except that you are allowed to set such a symbol to
itself.
@example
@ -118,8 +118,8 @@ nil @equiv{} 'nil
@end group
@end example
@tindex keyword-symbols-constant-flag
@defvar keyword-symbols-constant-flag
@tindex keyword-symbols-constant-flag
If this variable is @code{nil}, you are allowed to set and bind symbols
whose names start with @samp{:} as you wish. This is to make it
possible to run old Lisp programs which do that.
@ -247,27 +247,29 @@ Macro calls (@pxref{Macros}).
@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.
Variables}) and frame-local bindings (@pxref{Frame-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
@cindex infinite recursion
This variable defines the limit on the total number of local variable
This variable defines the limit on the total number of local variable
bindings and @code{unwind-protect} cleanups (@pxref{Nonlocal Exits})
that are allowed before signaling an error (with data @code{"Variable
binding depth exceeds max-specpdl-size"}).
This limit, with the associated error when it is exceeded, is one way
This limit, with the associated error when it is exceeded, is one way
that Lisp avoids infinite recursion on an ill-defined function.
The default value is 600.
@code{max-lisp-eval-depth} provides another limit on depth of nesting.
@code{max-lisp-eval-depth} provides another limit on depth of nesting.
@xref{Eval}.
The default value is 600. Entry to the Lisp debugger increases the
value, if there is little room left, to make sure the debugger itself
has room to execute.
@end defvar
@node Void Variables
@ -430,14 +432,15 @@ already has a value (i.e., it is not void), @var{value} is not even
evaluated, and @var{symbol}'s value remains unchanged. If @var{value}
is omitted, the value of @var{symbol} is not changed in any case.
If @var{symbol} has a buffer-local binding in the current buffer,
@code{defvar} operates on the default value, which is buffer-independent,
not the current (buffer-local) binding. It sets the default value if
the default value is void. @xref{Buffer-Local Variables}.
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} arranges to set the variable unconditionally even if
the variable already has a value.
If @var{symbol} has a buffer-local binding in the current buffer,
@code{defvar} sets the default (buffer-independent) value, not the
buffer-local value. @xref{Buffer-Local Variables}.
@code{eval-defun} arranges to set the variable unconditionally, without
testing whether its value is void.
If the @var{doc-string} argument appears, it specifies the documentation
for the variable. (This opportunity to specify documentation is one of
@ -518,9 +521,10 @@ symbol to be defined must appear explicitly in the @code{defconst}.
@code{defconst} always evaluates @var{value}, and sets the value of
@var{symbol} to the result if @var{value} is given. If @var{symbol}
does has a buffer-local binding in the current buffer, @code{defconst}
sets the default value, not the buffer-local value. But you should not
be making the symbol buffer-local if it is defined with @code{defconst}.
does have a buffer-local binding in the current buffer, @code{defconst}
sets the default value, not the buffer-local value. (But you should not
be making buffer-local bindings for a symbol that is defined with
@code{defconst}.)
Here, @code{pi} is a constant that presumably ought not to be changed
by anyone (attempts by the Indiana State Legislature notwithstanding).
@ -560,7 +564,7 @@ then the variable is a user option.
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
to @code{interactive} (@pxref{Using Interactive}). However, this feature
is largely obsoleted by the @code{defcustom} (@pxref{Customization}).
is largely obsoleted by @code{defcustom} (@pxref{Customization}).
@strong{Warning:} If the @code{defconst} and @code{defvar} special
forms are used while the variable has a local binding, they set the
@ -1069,7 +1073,7 @@ and/or frames is an important customization method.
This section describes buffer-local bindings; for frame-local
bindings, see the following section, @ref{Frame-Local Variables}. (A few
variables have bindings that are local to a X terminal; see
variables have bindings that are local to each X terminal; see
@ref{Multiple Displays}.)
@menu
@ -1137,8 +1141,8 @@ can scramble the values of the buffer-local and default bindings.
To preserve your sanity, avoid using a variable in that way. If you
use @code{save-excursion} around each piece of code that changes to a
different current buffer, you will not have this problem. Here is an
example of what to avoid:
different current buffer, you will not have this problem
(@pxref{Excursions}). Here is an example of what to avoid:
@example
@group
@ -1288,7 +1292,7 @@ then the variable appears directly in the resulting list.
(setq lcl (buffer-local-variables))
;; @r{First, built-in variables local in all buffers:}
@result{} ((mark-active . nil)
(buffer-undo-list nil)
(buffer-undo-list . nil)
(mode-name . "Fundamental")
@dots{}
@group
@ -1331,8 +1335,9 @@ result, the buffer will see the default values of most variables.
This function also resets certain other information pertaining to the
buffer: it sets the local keymap to @code{nil}, the syntax table to the
value of @code{standard-syntax-table}, and the abbrev table to the value
of @code{fundamental-mode-abbrev-table}.
value of @code{(standard-syntax-table)}, the case table to
@code{(standard-case-table)}, and the abbrev table to the value of
@code{fundamental-mode-abbrev-table}.
The very first thing this function does is run the normal hook
@code{change-major-mode-hook} (see below).
@ -1400,10 +1405,11 @@ default value is nonvoid. If @code{(default-boundp 'foo)} returns
@code{symbol-value}.
@end defun
@defspec setq-default symbol value
This sets the default value of @var{symbol} to @var{value}. It does not
evaluate @var{symbol}, but does evaluate @var{value}. The value of the
@code{setq-default} form is @var{value}.
@defspec setq-default [symbol form]@dots{}
This special form gives each @var{symbol} a new default value, which is
the result of evaluating the corresponding @var{form}. It does not
evaluate @var{symbol}, but does evaluate @var{form}. The value of the
@code{setq-default} form is the value of the last @var{form}.
If a @var{symbol} is not buffer-local for the current buffer, and is not
marked automatically buffer-local, @code{setq-default} has the same
@ -1492,17 +1498,18 @@ name as the parameter name.
To enable frame-local bindings for a certain variable, call the function
@code{make-variable-frame-local}.
@defun make-variable-frame-local variable
@deffn Command make-variable-frame-local variable
Enable the use of frame-local bindings for @var{variable}. This does
not in itself create any frame-local bindings for the variable; however,
if some frame already has a value for @var{variable} as a frame
parameter, that value automatically becomes a frame-local binding.
If the variable is terminal-local, this function signals an error. Such
variables cannot have buffer-local bindings as well. @xref{Multiple
Displays}. A few variables that are implemented specially in Emacs
can be (and usually are) buffer-local, but can never be frame-local.
@end defun
If the variable is terminal-local, this function signals an error,
because such variables cannot have frame-local bindings as well.
@xref{Multiple Displays}. A few variables that are implemented
specially in Emacs can be (and usually are) buffer-local, but can never
be frame-local.
@end deffn
Buffer-local bindings take precedence over frame-local bindings. Thus,
consider a variable @code{foo}: if the current buffer has a buffer-local

48
lispref/windows.texi
View file

@ -597,7 +597,9 @@ when you need complete control.
@defun set-window-buffer window buffer-or-name
This function makes @var{window} display @var{buffer-or-name} as its
contents. It returns @code{nil}.
contents. It returns @code{nil}. This is the fundamental primitive
for changing which buffer is displayed in a window, and all ways
of doing that call this function.
@example
@group
@ -669,6 +671,16 @@ If it is a frame, consider windows on that frame.
@end itemize
@end defun
@defvar buffer-display-time
@tindex buffer-display-time
This variable records the time at which a buffer was last made visible
in a window. It is always local in each buffer; each time
@code{set-window-buffer} is called, it sets this variable to
@code{(current-time)} in the specified buffer (@pxref{Time of Day}).
When a buffer is first created, @code{buffer-display-count} starts out
with the value @code{nil}.
@end defvar
@node Displaying Buffers
@section Displaying Buffers in Windows
@cindex switching to a buffer
@ -685,7 +697,8 @@ See the preceding section for
@ifinfo
@xref{Buffers and Windows}, for
@end ifinfo
low-level functions that give you more precise control.
low-level functions that give you more precise control. All of these
functions work by calling @code{set-window-buffer}.
Do not use the functions in this section in order to make a buffer
current so that a Lisp program can access or modify it; they are too
@ -786,14 +799,6 @@ don't care which other buffer is used; you just want to make sure that
This function returns @code{nil}.
@end deffn
@tindex buffer-display-count
@defvar buffer-display-count
This variable is always buffer-local in each buffer. When the buffer is
created, @code{buffer-display-count} has value 0. Each time the buffer
is displayed in a window, that increments the value of
@code{buffer-display-count}.
@end defvar
@node Choosing Window
@section Choosing a Window for Display
@ -1308,13 +1313,14 @@ Replaces three keystroke sequence C-u 0 C-l."
@section Horizontal Scrolling
@cindex horizontal scrolling
Because we read English first from top to bottom and second from left
to right, horizontal scrolling is not like vertical scrolling. Vertical
scrolling involves selection of a contiguous portion of text to display.
Horizontal scrolling causes part of each line to go off screen. The
amount of horizontal scrolling is therefore specified as a number of
columns rather than as a position in the buffer. It has nothing to do
with the display-start position returned by @code{window-start}.
Because we read English from left to right in the ``inner loop'', and
from top to bottom in the ``outer loop'', horizontal scrolling is not
like vertical scrolling. Vertical scrolling involves selection of a
contiguous portion of text to display, but horizontal scrolling causes
part of each line to go off screen. The amount of horizontal scrolling
is therefore specified as a number of columns rather than as a position
in the buffer. It has nothing to do with the display-start position
returned by @code{window-start}.
Usually, no horizontal scrolling is in effect; then the leftmost
column is at the left edge of the window. In this state, scrolling to
@ -1838,8 +1844,8 @@ over. In most cases, @code{save-selected-window} (@pxref{Selecting
Windows}) is what you need here.
@end defvar
@tindex redisplay-end-trigger-functions
@defvar redisplay-end-trigger-functions
@tindex redisplay-end-trigger-functions
This abnormal hook is run whenever redisplay in window uses text that
extends past a specified end trigger position. You set the end trigger
position with the function @code{set-window-redisplay-end-trigger}. The
@ -1849,19 +1855,19 @@ feature, and the trigger value is automatically reset to @code{nil} just
after the hook is run.
@end defvar
@tindex set-window-redisplay-end-trigger
@defun set-window-redisplay-end-trigger window position
@tindex set-window-redisplay-end-trigger
This function sets @var{window}'s end trigger position at
@var{position}.
@end defun
@tindex window-redisplay-end-trigger
@defun window-redisplay-end-trigger window
@tindex window-redisplay-end-trigger
This function returns @var{window}'s current end trigger position.
@end defun
@tindex window-configuration-change-hook
@defvar window-configuration-change-hook
@tindex window-configuration-change-hook
A normal hook that is run every time you change the window configuration
of an existing frame. This includes splitting or deleting windows,
changing the sizes of windows, or displaying a different buffer in a