Commit a9f0a989 authored by Richard M. Stallman's avatar Richard M. Stallman
Browse files

*** empty log message ***

parent c6d65724
...@@ -8,25 +8,96 @@ ...@@ -8,25 +8,96 @@
@cindex advising functions @cindex advising functions
The @dfn{advice} feature lets you add to the existing definition of a 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 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 Each piece of advice can be enabled or disabled explicitly. The
enabled pieces of advice for any given function actually take effect enabled pieces of advice for any given function actually take effect
when you activate advice for that function, or when that function is when you activate advice for that function, or when that function is
subsequently defined or redefined. 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 @menu
* Defining Advice:: * Simple Advice:: A simple example to explain the basics of advice.
* Computed Advice:: * Defining Advice:: Detailed description of @code{defadvice}.
* Activation of Advice:: * Computed Advice:: ...is to @code{defadvice} as @code{fset} is to @code{defun}.
* Enabling Advice:: * Activation of Advice:: Advice doesn't do anything until you activate it.
* Preactivation:: * Enabling Advice:: You can enable or disable each piece of advice.
* Argument Access in Advice:: * Preactivation:: Preactivation is a way of speeding up the
* Combined Definition:: 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 @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 @node Defining Advice
@section Defining Advice @section Defining Advice
...@@ -50,16 +121,11 @@ form) to be advised. From now on, we will write just ``function'' when ...@@ -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 describing the entity being advised, but this always includes macros and
special forms. special forms.
The argument @var{name} is the name of the advice, a non-@code{nil} @cindex class of advice
symbol. The advice name uniquely identifies one piece of advice, within all @cindex before-advice
the pieces of advice in a particular class for a particular @cindex after-advice
@var{function}. The name allows you to refer to the piece of @cindex around-advice
advice---to redefine it, or to enable or disable it. @var{class} specifies the @dfn{class} of the advice---one of @code{before},
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},
@code{after}, or @code{around}. Before-advice runs before the function @code{after}, or @code{around}. Before-advice runs before the function
itself; after-advice runs after the function itself; around-advice is itself; after-advice runs after the function itself; around-advice is
wrapped around the execution of the function itself. After-advice and 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 ...@@ -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 definition completely. (It also overrides lower-positioned pieces of
around-advice). 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 The optional @var{position} specifies where, in the current list of
advice of the specified @var{class}, this new advice should be placed. advice of the specified @var{class}, this new advice should be placed.
It should be either @code{first}, @code{last} or a number that 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 ...@@ -84,35 +159,49 @@ no position is specified, the default is @code{first}. The
advice. advice.
The optional @var{arglist} can be used to define the argument list for 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 the sake of advice. This becomes the argument list of the combined
with the argument list of the original function, otherwise functions definition that is generated in order to run the advice (@pxref{Combined
that call the advised function with the original argument list in mind Definition}). Therefore, the advice expressions can use the argument
will break. If more than one piece of advice specifies an argument variables in this list to access argument values.
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 list, then the first one (the one with the smallest position) found in
the list of all classes of advice will be used. the list of all classes of advice is used. Numbers outside the range
are mapped to the beginning or the end, whichever is closer.
@var{flags} is a list of symbols that specify further information about The remaining elements, @var{flags}, is a list of symbols that specify
how to use this piece of advice. Here are the valid symbols and their further information about how to use this piece of advice. Here are the
meanings: valid symbols and their meanings:
@table @code @table @code
@item activate @item activate
Activate all the advice for @var{function} after making this definition. Activate the advice for @var{function} now. Changes in a function's
This is ignored when @var{function} itself is not defined yet (which is advice always take effect the next time you activate advice for the
known as @dfn{forward advice}). 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 @item protect
Protect this piece of advice against non-local exits and errors in 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 @item compile
Says that the combined definition which implements advice should be Compile the combined definition that is used to run the advice. This
byte-compiled. This flag is ignored unless @code{activate} is also flag is ignored unless @code{activate} is also specified.
specified. @xref{Combined Definition}.
@item disable @item disable
Disable this piece of advice, so that it will not be used Initially disable this piece of advice, so that it will not be used
unless subsequently explicitly enabled. unless subsequently explicitly enabled. @xref{Enabling Advice}.
@item preactivate @item preactivate
Activate advice for @var{function} when this @code{defadvice} is 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. ...@@ -124,10 +213,10 @@ This is useful only if this @code{defadvice} is byte-compiled.
@end table @end table
The optional @var{documentation-string} serves to document this piece of The optional @var{documentation-string} serves to document this piece of
advice. If the @code{documentation} function gets the documentation advice. When advice is active for @var{function}, the documentation for
for @var{function} when its advice is active, the result will combine @var{function} (as returned by @code{documentation}) combines the
the documentation strings of all the advice with that of the original documentation strings of all the advice for @var{function} with the
function. documentation string of its original function definition.
The optional @var{interactive-form} form can be supplied to change the The optional @var{interactive-form} form can be supplied to change the
interactive behavior of the original function. If more than one piece interactive behavior of the original function. If more than one piece
...@@ -162,7 +251,9 @@ this form: ...@@ -162,7 +251,9 @@ this form:
@end example @end example
Here @var{protected} and @var{enabled} are flags, and @var{definition} 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 If @var{function} already has one or more pieces of advice in the
specified @var{class}, then @var{position} specifies where in the list 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 ...@@ -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 importantly, it permits defining advice for a function before that
function is actually defined. function is actually defined.
When a function is first activated, its original definition is saved, When a function's advice is first activated, the function's original
and all enabled pieces of advice for that function are combined with the definition is saved, and all enabled pieces of advice for that function
original definition to make a new definition. This definition is are combined with the original definition to make a new definition.
installed, and optionally byte-compiled as well, depending on conditions (Pieces of advice that are currently disabled are not used; see
described below. @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}, In all of the commands to activate advice, if @var{compile} is @code{t},
the command also compiles the combined definition which implements the the command also compiles the combined definition which implements the
...@@ -208,9 +300,9 @@ advice. ...@@ -208,9 +300,9 @@ advice.
This command activates the advice for @var{function}. This command activates the advice for @var{function}.
@end deffn @end deffn
To activate a function whose advice is already active is not a no-op. To activate advice for a function whose advice is already active is not
It is a useful operation which puts into effect any changes in advice a no-op. It is a useful operation which puts into effect any changes in
since the previous activation of the same function. advice since the previous activation of that function's advice.
@deffn Command ad-deactivate function @deffn Command ad-deactivate function
This command deactivates the advice for @var{function}. This command deactivates the advice for @var{function}.
...@@ -239,15 +331,21 @@ function which has at least one piece of advice that matches ...@@ -239,15 +331,21 @@ function which has at least one piece of advice that matches
@deffn Command ad-update-regexp regexp &optional compile @deffn Command ad-update-regexp regexp &optional compile
This command activates pieces of advice whose names match @var{regexp}, This command activates pieces of advice whose names match @var{regexp},
but only those that are already activated. but only those for functions whose advice is already activated.
@end deffn
@deffn Command ad-stop-advice Reactivating a function's advice is useful for putting into effect all
Turn off automatic advice activation when a function is defined or the changes that have been made in its advice (including enabling and
redefined. disabling specific pieces of advice; @pxref{Enabling Advice}) since the
last time it was activated.
@end deffn @end deffn
@deffn Command ad-start-advice @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 Turn off automatic advice activation when a function is defined or
redefined. redefined.
@end deffn @end deffn
...@@ -275,8 +373,8 @@ the function @code{foo}: ...@@ -275,8 +373,8 @@ the function @code{foo}:
(ad-disable-advice 'foo 'before 'my-advice) (ad-disable-advice 'foo 'before 'my-advice)
@end example @end example
This call by itself only changes the enable flag for this piece of This function by itself only changes the enable flag for a piece of
advice. To make this change take effect in the advised definition, you advice. To make the change take effect in the advised definition, you
must activate the advice for @code{foo} again: must activate the advice for @code{foo} again:
@example @example
...@@ -293,8 +391,10 @@ This command enables the piece of advice named @var{name} in class ...@@ -293,8 +391,10 @@ This command enables the piece of advice named @var{name} in class
@var{class} on @var{function}. @var{class} on @var{function}.
@end deffn @end deffn
You can also disable many pieces of advice at once using a regular You can also disable many pieces of advice at once, for various
expression. 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 @deffn Command ad-disable-regexp regexp
This command disables all pieces of advice whose names match This command disables all pieces of advice whose names match
...@@ -322,12 +422,12 @@ same function, and the function's own definition. If the ...@@ -322,12 +422,12 @@ same function, and the function's own definition. If the
@code{defadvice} is compiled, that compiles the combined definition @code{defadvice} is compiled, that compiles the combined definition
also. also.
When the function is subsequently activated, if the enabled advice for When the function's advice is subsequently activated, if the enabled
the function matches what was used to make this combined advice for the function matches what was used to make this combined
definition. then the existing combined definition is used, and there is definition, then the existing combined definition is used, thus avoiding
no need to construct one. Thus, preactivation never causes wrong 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 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 Here are some symptoms that can indicate that a preactivation did not
work properly, because of a mismatch. work properly, because of a mismatch.
...@@ -351,8 +451,8 @@ when you @emph{compile} the preactivated advice. ...@@ -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 There is no elegant way to find out why preactivated advice is not being
used. What you can do is to trace the function used. What you can do is to trace the function
@code{ad-cache-id-verification-code} (with the function @code{ad-cache-id-verification-code} (with the function
@code{trace-function-background}) before the advised function is @code{trace-function-background}) before the advised function's advice
activated. After activation, check the value returned by is activated. After activation, check the value returned by
@code{ad-cache-id-verification-code} for that function: @code{verified} @code{ad-cache-id-verification-code} for that function: @code{verified}
means that the preactivated advice was used, while other values give means that the preactivated advice was used, while other values give
some information about why they were considered inappropriate. some information about why they were considered inappropriate.
...@@ -376,6 +476,13 @@ disadvantage: it is not robust, because it hard-codes the argument names ...@@ -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, into the advice. If the definition of the original function changes,
the advice might break. 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 A more robust method is to use macros that are translated into the
proper access forms at activation time, i.e., when constructing the proper access forms at activation time, i.e., when constructing the
advised definition. Access macros access actual arguments by position 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 ...@@ -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. These argument constructs are not really implemented as Lisp macros.
Instead they are implemented specially by the advice mechanism. 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 When the advice facility constructs the combined definition, it needs
to know the argument list of the original function. This is not always to know the argument list of the original function. This is not always
......
...@@ -7,7 +7,7 @@ ...@@ -7,7 +7,7 @@
For those users who live backwards in time, here is information about 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 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 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. 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. ...@@ -29,9 +29,10 @@ Within this range, there are no invalid character codes.
@item @item
The Custom facility has been replaced with a much simpler and more The Custom facility has been replaced with a much simpler and more
general method of defining user option variables. Instead of general method of defining user option variables. Instead of
@code{defcustom}, which requires you to specify each user option's @code{defcustom}, which requires you to specify each user option's data
data type and classify them into groups, all you have to do is write type and classify options into groups, all you have to do is write a
a @code{defvar} and start the documentation string with @samp{*}. @code{defvar}. You should still start the documentation string with
@samp{*}, though.
@end itemize @end itemize
Here are changes in the Lisp language itself: Here are changes in the Lisp language itself:
...@@ -138,7 +139,7 @@ directory name from the beginning of the file name---just like ...@@ -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}. We have got rid of the function @code{access-file}.
@item @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. 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, This means that if you insert text with text properties into the minibuffer,
the minibuffer value really will contain text properties. the minibuffer value really will contain text properties.
......
...@@ -289,7 +289,8 @@ This function returns a string that is the name to use for a ...@@ -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 non-numbered backup file for file @var{filename}. On Unix, this is just
@var{filename} with a tilde appended. @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 @smallexample
@group @group
...@@ -306,7 +307,9 @@ to prepend a @samp{.} in addition to appending a tilde: ...@@ -306,7 +307,9 @@ to prepend a @samp{.} in addition to appending a tilde:
@smallexample @smallexample
@group @group
(defun make-backup-file-name (filename) (defun make-backup-file-name (filename)
(concat "." filename "~")) (expand-file-name
(concat "." (file-name-nondirectory filename) "~")
(file-name-directory filename)))
@end group @end group
@group @group
...@@ -314,6 +317,11 @@ to prepend a @samp{.} in addition to appending a tilde: ...@@ -314,6 +317,11 @@ to prepend a @samp{.} in addition to appending a tilde:
@result{} ".backups.texi~" @result{} ".backups.texi~"
@end group @end group
@end smallexample @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 @end defun
@defun find-backup-file-name filename @defun find-backup-file-name filename
......
...@@ -47,9 +47,9 @@ not be displayed in any windows. ...@@ -47,9 +47,9 @@ not be displayed in any windows.
Buffers in Emacs editing are objects that have distinct names and hold 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 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 data type. You can think of the contents of a buffer as a string that
string; insertions and deletions may occur in any part of the buffer. you can extend; insertions and deletions may occur in any part of the
@xref{Text}. buffer. @xref{Text}.
A Lisp buffer object contains numerous pieces of information. Some of A Lisp buffer object contains numerous pieces of information. Some of
this information is directly accessible to the programmer through this information is directly accessible to the programmer through
...@@ -112,7 +112,7 @@ the subroutine does not change which buffer is current (unless, of ...@@ -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 course, that is the subroutine's purpose). Therefore, you should
normally use @code{set-buffer} within a @code{save-current-buffer} or normally use @code{set-buffer} within a @code{save-current-buffer} or
@code{save-excursion} (@pxref{Excursions}) form that will restore the @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 code for the command @code{append-to-buffer} (with the documentation
string abridged): string abridged):
...@@ -201,8 +201,8 @@ An error is signaled if @var{buffer-or-name} does not identify an ...@@ -201,8 +201,8 @@ An error is signaled if @var{buffer-or-name} does not identify an
existing buffer. existing buffer.
@end defun @end defun
@defspec save-current-buffer body...
@tindex save-current-buffer @tindex save-current-buffer
@defmac save-current-buffer body...
The @code{save-current-buffer} macro saves the identity of the current The @code{save-current-buffer} macro saves the identity of the current
buffer, evaluates the @var{body} forms, and finally restores that buffer buffer, evaluates the @var{body} forms, and finally restores that buffer
as current. The return value is the value of the last form in 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 ...@@ -215,8 +215,8 @@ of course. Instead, whichever buffer was current just before exit
remains current. remains current.
@end defmac @end defmac
@tindex with-current-buffer
@defmac with-current-buffer buffer body... @defmac with-current-buffer buffer body...
@tindex with-current-buffer
The @code{with-current-buffer} macro saves the identity of the current The @code{with-current-buffer} macro saves the identity of the current
buffer, makes @var{buffer} current, evaluates the @var{body} forms, and buffer, makes @var{buffer} current, evaluates the @var{body} forms, and
finally restores the buffer. The return value is the value of the last 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 ...@@ -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}). abnormal exit via @code{throw} or error (@pxref{Nonlocal Exits}).
@end defmac @end defmac
@tindex with-temp-buffer
@defmac with-temp-buffer body... @defmac with-temp-buffer body...
@tindex with-temp-buffer
The @code{with-temp-buffer} macro evaluates the @var{body} forms The @code{with-temp-buffer} macro evaluates the @var{body} forms
with a temporary buffer as the current buffer. It saves the identity of with a temporary buffer as the current buffer. It saves the identity of
the current buffer, creates a temporary buffer and makes it current, the current buffer, creates a temporary buffer and makes it current,
......
...@@ -332,6 +332,10 @@ Prompt. ...@@ -332,6 +332,10 @@ Prompt.
@item F @item F
A file name. The file need not exist. Completion, Default, Prompt. 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 @item k
A key sequence (@pxref{Keymap Terminology}). This keeps reading events A key sequence (@pxref{Keymap Terminology}). This keeps reading events
until a command (or undefined command) is found in the current key until a command (or undefined command) is found in the current key
...@@ -408,6 +412,16 @@ Minibuffer}. Prompt. ...@@ -408,6 +412,16 @@ Minibuffer}. Prompt.
@cindex evaluated expression argument @cindex evaluated expression argument
A Lisp form is read as with @kbd{x}, but then evaluated so that its A Lisp form is read as with @kbd{x}, but then evaluated so that its
value becomes the argument for the command. Prompt. 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 @end table
@node Interactive Examples @node Interactive Examples
...@@ -758,8 +772,15 @@ are characters or symbols; mouse events are always lists. This section ...@@ -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.