library to customize functions defined by other parts of Emacs---cleaner
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.
+@cindex piece of advice
+ Each function can have multiple @dfn{pieces of advice}, separately
+defined. Each defined piece of advice can be enabled or disabled
+explicitly. The enabled pieces of advice for any given function
+actually take effect when you @dfn{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
@menu
* Simple Advice:: A simple example to explain the basics of advice.
* Defining Advice:: Detailed description of @code{defadvice}.
+* Around-Advice:: Wrapping advice around a function's definition.
* 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.
+* Argument Access in Advice:: How advice can access the function's arguments.
* Subr Arguments:: Accessing arguments when advising a primitive.
* Combined Definition:: How advice is implemented.
@end menu
(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
@node Defining Advice
@section Defining Advice
+@cindex defining advice
+@cindex advice, defining
To define a piece of advice, use the macro @code{defadvice}. A call
to @code{defadvice} has the following syntax, which is based on the
-syntax of @code{defun}/@code{defmacro} but adds more:
+syntax of @code{defun} and @code{defmacro}, but adds more:
@findex defadvice
@example
around-advice can override the return value by setting
@code{ad-return-value}.
-Around-advice specifies where the ``original'' function definition
-should go by means of the special symbol @code{ad-do-it}. Where this
-symbol occurs inside the around-advice body, it is replaced with a
-@code{progn} containing the forms of the surrounded code. If the
-around-advice does not use @code{ad-do-it}, then the original function
-definition is never run. This provides a way to override the original
-definition completely. (It also overrides lower-positioned pieces of
-around-advice).
+@defvar ad-return-value
+While advice is executing, after the function's original definition has
+been executed, this variable holds its return value, which will
+ultimately be returned to the caller after finishing all the advice.
+After-advice and around-advice can arrange to return some other value
+by storing it in this variable.
+@end defvar
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 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
-specifies a zero-based position (@code{first} is equivalent to 0). If
-no position is specified, the default is @code{first}. The
-@var{position} value is ignored when redefining an existing piece of
-advice.
+It should be either @code{first}, @code{last} or a number that specifies
+a zero-based position (@code{first} is equivalent to 0). If no position
+is specified, the default is @code{first}. Position values outside the
+range of existing positions in this class are mapped to the beginning or
+the end of the range, whichever is closer. The @var{position} value is
+ignored when redefining an existing piece of advice.
The optional @var{arglist} can be used to define the argument list for
the sake of advice. This becomes the argument list of the combined
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 list of all classes of advice is used.
-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:
+The remaining elements, @var{flags}, are 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
@item protect
Protect this piece of advice against non-local exits and errors in
-preceding code and advice. Protecting advice makes it a cleanup in an
-@code{unwind-protect} form, so that it will execute even if the
+preceding code and advice. Protecting advice places it as 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
All subroutines used by the advice need to be available when the byte
compiler expands the macro.
+@node Around-Advice
+@section Around-Advice
+
+ Around-advice lets you ``wrap'' a Lisp expression ``around'' the
+original function definition. You specify where the original function
+definition should go by means of the special symbol @code{ad-do-it}.
+Where this symbol occurs inside the around-advice body, it is replaced
+with a @code{progn} containing the forms of the surrounded code. Here
+is an example:
+
+@example
+(defadvice foo (around foo-around)
+ "Ignore case in `foo'."
+ (let ((case-fold-search t))
+ ad-do-it))
+@end example
+
+@noindent
+Its effect is to make sure that case is ignored in
+searches when the original definition of @code{foo} is run.
+
+@defvar ad-do-it
+This is not really a variable, but it is somewhat used like one
+in around-advice. It specifies the place to run the function's
+original definition and other ``earlier'' around-advice.
+@end defvar
+
+If the around-advice does not use @code{ad-do-it}, then it does not run
+the original function definition. This provides a way to override the
+original definition completely. (It also overrides lower-positioned
+pieces of around-advice).
+
@node Computed Advice
@section Computed Advice
@node Activation of Advice
@section Activation of Advice
@cindex activating advice
+@cindex advice, activating
By default, advice does not take effect when you define it---only when
you @dfn{activate} advice for the function that was advised. You can
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.
+that function's advice since the previous activation of advice for that
+function.
@deffn Command ad-deactivate function
This command deactivates the advice for @var{function}.
+@cindex deactivating advice
+@cindex advice, deactivating
@end deffn
@deffn Command ad-activate-all &optional compile
@end deffn
@deffn Command ad-deactivate-regexp regexp
-This command deactivates the advice for all functions whose names match
+This command deactivates all pieces of advice whose names match
@var{regexp}. More precisely, it deactivates all advice for any
function which has at least one piece of advice that matches
@var{regexp}.
@deffn Command ad-update-regexp regexp &optional compile
This command activates pieces of advice whose names match @var{regexp},
but only those for functions whose advice is already activated.
+@cindex reactivating advice
Reactivating a function's advice is useful for putting into effect all
the changes that have been made in its advice (including enabling and
that results from activating advice for a function.
@end defopt
- If the advised definition was constructed during ``preactivation'' (see
-below), then that definition must already be compiled, because it was
-constructed during byte-compilation of the file that contained the
-@code{defadvice} with the @code{preactivate} flag.
+ If the advised definition was constructed during ``preactivation''
+(@pxref{Preactivation}), then that definition must already be compiled,
+because it was constructed during byte-compilation of the file that
+contained the @code{defadvice} with the @code{preactivate} flag.
@node Enabling Advice
@section Enabling and Disabling Advice
+@cindex enabling advice
+@cindex advice, enabling and disabling
+@cindex disabling advice
Each piece of advice has a flag that says whether it is enabled or
-not. By enabling or disabling a piece of advice, you can turn it off
-and on without having to undefine and redefine it. For example, here is
+not. By enabling or disabling a piece of advice, you can turn it on
+and off without having to undefine and redefine it. For example, here is
how to disable a particular piece of advice named @code{my-advice} for
the function @code{foo}:
(ad-disable-advice 'foo 'before 'my-advice)
@end example
-This function by itself only changes the enable flag for a piece of
+ 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:
@node Preactivation
@section Preactivation
+@cindex preactivating advice
+@cindex advice, preactivating
Constructing a combined definition to execute advice is moderately
expensive. When a library advises many functions, this can make loading
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
-regardless of how these actual argument get distributed onto the
+regardless of how these actual arguments get distributed onto the
argument variables of a function. This is robust because in Emacs Lisp
the meaning of an argument is strictly determined by its position in the
argument list.
or specified padding.
@item
-The functions @code{split-string} and @code{concat-chars} no longer exist.
+The functions @code{split-string} and @code{string} no longer exist.
Neither does @code{store-substring} or @code{sref}.
@item
of the file with the @code{revert-buffer} command. @xref{Reverting, ,
Reverting a Buffer, emacs, The GNU Emacs Manual}.
-@deffn Command revert-buffer &optional check-auto-save noconfirm
+@deffn Command revert-buffer &optional ignore-auto noconfirm
This command replaces the buffer text with the text of the visited
file on disk. This action undoes all changes since the file was visited
or saved.
-If the argument @var{check-auto-save} is non-@code{nil}, and the
-latest auto-save file is more recent than the visited file,
-@code{revert-buffer} asks the user whether to use that instead.
-Otherwise, it always uses the text of the visited file itself.
-Interactively, @var{check-auto-save} is set if there is a numeric prefix
-argument.
+By default, if the latest auto-save file is more recent than the visited
+file, @code{revert-buffer} asks the user whether to use that instead.
+But if the argument @var{ignore-auto} is non-@code{nil}, then only the
+the visited file itself is used. Interactively, @var{ignore-auto} is
+@code{t} unless there is a numeric prefix argument; thus, the
+interactive default is to check the auto-save file.
Normally, @code{revert-buffer} asks for confirmation before it changes
the buffer; but if the argument @var{noconfirm} is non-@code{nil},
You can customize how @code{revert-buffer} does its work by setting
these variables---typically, as buffer-local variables.
+@defvar revert-without-query
+This variable holds a list of files that should be reverted without
+query. The value is a list of regular expressions. If a file name
+matches one of these regular expressions, then @code{revert-buffer}
+reverts the file without asking the user for confirmation, if the file
+has changed on disk and the buffer is not modified.
+@end defvar
+
@defvar revert-buffer-function
The value of this variable is the function to use to revert this buffer.
If non-@code{nil}, it is called as a function with no arguments to do
exit from @code{save-current-buffer}, then it is not made current again,
of course. Instead, whichever buffer was current just before exit
remains current.
-@end defmac
+@end defspec
@defmac with-current-buffer buffer body...
@tindex with-current-buffer
such buffer in the buffer list.
@end defun
-@deffn Command set-visited-file-name filename
+@deffn Command set-visited-file-name filename &optional no-query along-with-file
If @var{filename} is a non-empty string, this function changes the
name of the file visited in current buffer to @var{filename}. (If the
buffer had no visited file, this gives it one.) The @emph{next time}
``no visited file''. In this case, @code{set-visited-file-name} marks
the buffer as having no visited file.
+Normally, this function asks the user for confirmation if the specified
+file already exists. If @var{no-query} is non-@code{nil}, that prevents
+asking this question.
+
+If @var{along-with-file} is non-@code{nil}, that means to assume that the
+former visited file has been renamed to @var{filename}.
+
@c Wordy to avoid overfull hbox. --rjc 16mar92
When the function @code{set-visited-file-name} is called interactively, it
prompts for @var{filename} in the minibuffer.
@code{buffer-list} frame parameter with @code{modify-frame-parameters}
(@pxref{Parameter Access}).
-@defun other-buffer &optional buffer visible-ok
+@defun other-buffer &optional buffer visible-ok frame
This function returns the first buffer in the buffer list other than
-@var{buffer}. Usually this is the buffer selected most recently (in the
-currently selected frame), aside from @var{buffer}. Buffers whose names
-start with a space are not considered at all.
+@var{buffer}. Usually this is the buffer selected most recently (in
+frame @var{frame} or else the currently selected frame), aside from
+@var{buffer}. Buffers whose names start with a space are not considered
+at all.
If @var{buffer} is not supplied (or if it is not a buffer), then
@code{other-buffer} returns the first buffer in the selected frame's
buffer list that is not now visible in any window in a visible frame.
-If the selected frame has a non-@code{nil} @code{buffer-predicate}
-parameter, then @code{other-buffer} uses that predicate to decide which
-buffers to consider. It calls the predicate once for each buffer, and
-if the value is @code{nil}, that buffer is ignored. @xref{Window Frame
-Parameters}.
+If @var{frame} has a non-@code{nil} @code{buffer-predicate} parameter,
+then @code{other-buffer} uses that predicate to decide which buffers to
+consider. It calls the predicate once for each buffer, and if the value
+is @code{nil}, that buffer is ignored. @xref{Window Frame Parameters}.
@c Emacs 19 feature
If @var{visible-ok} is @code{nil}, @code{other-buffer} avoids returning
@noindent
and would appear in the diary for any date that corresponds to Heshvan 25
-on the Hebrew calendar. And here is Islamic-date diary entry that matches
+on the Hebrew calendar. And here is an Islamic-date diary entry that matches
Dhu al-Qada 25:
@smallexample
@cindex sorting diary entries
If you use the fancy diary display, you can use the normal hook
@code{list-diary-entries-hook} to sort each day's diary entries by their
-time of day. Here's how
+time of day. Here's how:
@findex sort-diary-entries
@example
(- (point-max) (point-min))))
@end example
-Recall that scroll bar events have two integers forming ratio in place
+Recall that scroll bar events have two integers forming a ratio, in place
of a pair of x and y coordinates.
@end defun
To support programs with @samp{\M-} in string constants, there are
special rules for including certain meta characters in a string.
-Here are the rules for interpreting keyboard
+Here are the rules for interpreting a string as a sequence of input
+characters:
@itemize @bullet
@item
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
+If @code{read-event} gets an event that 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
This section describes how to ``peek ahead'' at events without using
them up, how to check for pending input, and how to discard pending
-input.
+input. See also the function @code{read-passwd} (@pxref{Reading a
+Password}).
@defvar unread-command-events
@cindex next input
@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}.
+You can use the @code{:options} keyword in a hook variable's
+@code{defcustom} to specify a list of 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
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
+criteria specified by the values of @code{debug-on-error} and
@code{debug-ignored-errors}.
@strong{Warning:} This variable is strong medicine! Various parts of
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
+@code{debug-on-error} to @code{t} while loading @file{.emacs}, and
bypasses the @code{condition-case} which normally catches errors in the
-init-file.
+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
and you have put back those parentheses, @kbd{C-M-q} should not change
anything.
-@node Compilation Errors, Edebug, Syntax Errors, Debugging
+@node Compilation Errors
@section Debugging Problems in Compilation
When an error happens during byte compilation, it is normally due to
@menu
* Refresh Screen:: Clearing the screen and redrawing everything on it.
-* Screen Size:: How big is the Emacs screen.
* Truncation:: Folding or wrapping long text lines.
* The Echo Area:: Where messages are displayed.
* Invisible Text:: Hiding part of the buffer text.
@section Refreshing the Screen
The function @code{redraw-frame} redisplays the entire contents of a
-given frame. @xref{Frames}.
+given frame (@pxref{Frames}).
@c Emacs 19 feature
@defun redraw-frame frame
to redraw, @code{nil} means redrawing is needed. The default is @code{nil}.
@end defvar
-@node Screen Size
-@section Screen Size
-@cindex size of screen
-@cindex screen size
-@cindex display lines
-@cindex display columns
-@cindex resize redisplay
-
- The screen size functions access or specify the height or width of
-the terminal. When you are using multiple frames, they apply to the
-selected frame (@pxref{Frames}).
-
-@defun screen-height
-This function returns the number of lines on the screen that are
-available for display.
-
-@example
-@group
-(screen-height)
- @result{} 50
-@end group
-@end example
-@end defun
-
-@defun screen-width
-This function returns the number of columns on the screen that are
-available for display.
-
-@example
-@group
-(screen-width)
- @result{} 80
-@end group
-@end example
-@end defun
-
-@defun set-screen-height lines &optional not-actual-size
-This function declares that the terminal can display @var{lines} lines.
-The sizes of existing windows are altered proportionally to fit.
-
-If @var{not-actual-size} is non-@code{nil}, then Emacs displays
-@var{lines} lines of output, but does not change its value for the
-actual height of the screen. (Knowing the correct actual size may be
-necessary for correct cursor positioning.) Using a smaller height than
-the terminal actually implements may be useful to reproduce behavior
-observed on a smaller screen, or if the terminal malfunctions when using
-its whole screen.
-
-If @var{lines} is different from what it was previously, then the
-entire screen is cleared and redisplayed using the new size.
-
-This function returns @code{nil}.
-@end defun
-
-@defun set-screen-width columns &optional not-actual-size
-This function declares that the terminal can display @var{columns}
-columns. The details are as in @code{set-screen-height}.
-@end defun
-
@node Truncation
@section Truncation
@cindex line wrapping
You can override the glyphs that indicate continuation or truncation
using the display table; see @ref{Display Tables}.
- If your buffer contains @strong{very} long lines, and you use
+ If your buffer contains @emph{very} long lines, and you use
continuation to display them, just thinking about them can make Emacs
redisplay slow. The column computation and indentation functions also
become slow. Then you might find it advisable to set
During the search, such overlays are made temporarily visible by
temporarily modifying their invisible and intangible properties. If you
-want this to be done differently for a certain overlays, give it a
+want this to be done differently for a certain overlay, 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{t} to make the overlay visible, or @code{nil} to
@code{t} is used in the last (or only) element of @var{spec}.
@item a list
-If @var{display} is alist, each elements should have the form
+If @var{display} is a list, each element should have the form
@code{(@var{characteristic} @var{value}@dots{})}. Here
@var{characteristic} specifies a way of classifying frames, and the
@var{value}s are possible classifications which @var{display} should
@code{grayscale}, or @code{mono}.
@item background
-The kind of background--- either @code{light} or @code{dark}.
+The kind of background---either @code{light} or @code{dark}.
@end table
If an element of @var{display} specifies more than one @var{value} for a
with the customization buffer, and @code{face-documentation} for the
documentation string.
+@tindex frame-background-mode
+@defopt frame-background-mode
+This option, if non-@code{nil}, specifies the background type to use for
+interpreting face definitions. If it is @code{dark}, then Emacs treats
+all frames as if they had a dark background, regardless of their actual
+background colors. If it is @code{light}, then Emacs treats all frames
+as if they had a light background.
+@end defopt
+
@node Merging Faces
@subsection Merging Faces for Display
Normally, the value is the face number of the face named @code{region}.
@end defvar
+@tindex frame-update-face-colors
+@defun frame-update-face-colors frame
+This function updates the way faces display on @var{frame}, for a change
+in @var{frame}'s foreground or background color.
+@end defun
+
@node Blinking
@section Blinking Parentheses
@cindex parenthesis matching
case nothing is done.
@end defvar
-@defvar blink-matching-paren
+@defopt blink-matching-paren
If this variable is @code{nil}, then @code{blink-matching-open} does
nothing.
-@end defvar
+@end defopt
-@defvar blink-matching-paren-distance
+@defopt blink-matching-paren-distance
This variable specifies the maximum distance to scan for a matching
parenthesis before giving up.
-@end defvar
+@end defopt
-@defvar blink-matching-paren-delay
+@defopt blink-matching-delay
This variable specifies the number of seconds for the cursor to remain
at the matching parenthesis. A fraction of a second often gives
good results, but the default is 1, which works on all systems.
-@end defvar
+@end defopt
-@defun blink-matching-open
+@deffn Command blink-matching-open
This function is the default value of @code{blink-paren-function}. It
assumes that point follows a character with close parenthesis syntax and
moves the cursor momentarily to the matching opening character. If that
(blink-matching-open)))
@end group
@end smallexample
-@end defun
+@end deffn
@node Inverse Video
@section Inverse Video
Here are the possible types of elements in the glyph table:
-@table @var
-@item string
+@table @asis
+@item @var{string}
Send the characters in @var{string} to the terminal to output
this glyph. This alternative is available on character terminals,
but not under a window system.
-@item integer
+@item @var{integer}
Define this glyph code as an alias for glyph code @var{integer}. You
can use an alias to specify a face code for the glyph; see below.
This is a synonym for @code{ding}.
@end defun
-@defvar visible-bell
+@defopt visible-bell
This variable determines whether Emacs should flash the screen to
represent a bell. Non-@code{nil} means yes, @code{nil} means no. This
is effective on a window system, and on a character-only terminal
provided the terminal's Termcap entry defines the visible bell
capability (@samp{vb}).
-@end defvar
+@end defopt
@defvar ring-bell-function
@tindex ring-bell-function
concerned; the individual Emacs windows are not known to X at all.
@defvar window-system
-@cindex X Window System
This variable tells Lisp programs what window system Emacs is running
-under. Its value should be a symbol such as @code{x} (if Emacs is
-running under X) or @code{nil} (if Emacs is running on an ordinary
-terminal).
+under. The possible values are
+
+@table @code
+@item x
+@cindex X Window System
+Emacs is displaying using X.
+@item pc
+Emacs is displaying using MSDOS.
+@item w32
+Emacs is displaying using Windows NT or Windows 95.
+@item nil
+Emacs is using a character-based terminal.
+@end table
@end defvar
@defvar window-setup-hook
@c , Bugs and Todo List, Top, Top
-@node Edebug,, Compilation Errors, Debugging
+@node Edebug, Syntax Errors, Debugger, Debugging
@section Edebug
@cindex Edebug mode
pause for @var{n} seconds instead.
@item w
-Move point back to the current stop point (@code{edebug-where}) in the
-source code buffer. Also, if you use this command in a different window
-displaying the same buffer, that window will be used instead to display
-the current definition in the future.
+Move point back to the current stop point in the source code buffer
+(@code{edebug-where}).
+
+If you use this command in a different window displaying the same
+buffer, that window will be used instead to display the current
+definition in the future.
@item W
@c Its function is not simply to forget the saved configuration -- dan
It also appends a newline to separate entries.
@end defun
- @code{edebug-tracing} and @code{edebug-trace} insert lines in the trace
-buffer even if Edebug is not active.
-
- Adding text to the trace buffer also scrolls its window to show the
-last lines inserted.
+ @code{edebug-tracing} and @code{edebug-trace} insert lines in the
+trace buffer whenever they are called, even if Edebug is not active.
+Adding text to the trace buffer also scrolls its window to show the last
+lines inserted.
@node Coverage Testing
@subsection Coverage Testing
@cindex frequency counts
@cindex performance analysis
Edebug provides rudimentary coverage testing and display of execution
-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
+frequency.
+
+ Coverage testing works by comparing the result of each expression with
+the previous result; each form in the program is considered ``covered''
+if it has returned two different values since you began testing coverage
+in the current Emacs session. Thus, to do coverage testing on your
+program, execute it under various conditions and note whether it behaves
+correctly; Edebug will tell you when you have tried enough different
+conditions that each form has returned two different values.
+
+ 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
The character @samp{=} following the count for an expression says that
the expression has returned the same value each time it was evaluated.
-This is the only coverage information that Edebug records.
+In other words, it is not yet ``covered'' for coverage testing purposes.
To clear the frequency count and coverage data for a definition,
simply reinstrument it with @code{eval-defun}.
@end deffn
Here is a simple example that defines the specification for the
-@code{for} example macro (@code{Argument Evaluation}), followed by an
+@code{for} example macro (@pxref{Argument Evaluation}), followed by an
alternative, equivalent specification.
@example
@table @code
@item sexp
-A single unevaluated expression, which is not instrumented.
+A single unevaluated Lisp object, which is not instrumented.
@c an "expression" is not necessarily intended for evaluation.
@item form
@item &rest
@kindex &rest @r{(Edebug)}
All following elements in the specification list are repeated zero or
-more times. All the elements need not match in the last repetition,
-however.
+more times. In the last repetition, however, it is ok if the expression
+runs out before matching all of the elements of the specification list.
To repeat only a few elements, use @code{[&rest @var{specs}@dots{}]}.
To specify several elements that must all match on every repetition, use
@titlepage
@title GNU Emacs Lisp Reference Manual
-@subtitle GNU Emacs Version 20
-@subtitle for Unix Users
+@subtitle For Emacs Version 20.3
@c The edition number appears in several places in this file
@c and also in the file intro.texi.
-@subtitle Revision 2.5, February 1998
+@subtitle Revision 2.5, May 1998
@author by Bil Lewis, Dan LaLiberte, Richard Stallman
@author and the GNU Manual Group
@sp 2
Edition 2.5 @*
Revised for Emacs Version 20.3,@*
-February 1998.@*
+May 1998.@*
@sp 2
-ISBN 1-882114-71-X
+ISBN 1-882114-72-8
@sp 2
Published by the Free Software Foundation @*
* Process Type:: A process running on the underlying OS.
* Stream Type:: Receive or send characters.
* Keymap Type:: What function a keystroke invokes.
-* Overlay Type:: How an overlay is represented.
+* Overlay Type:: How an overlay is represented.
Numbers
* Creating Strings:: Functions to allocate new strings.
* 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.
Lists
* 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.
+* Argument Access in Advice:: How advice can access the function's arguments.
* Subr Arguments:: Accessing arguments when advising a primitive.
* Combined Definition:: How advice is implemented.
* Input Focus:: Specifying the selected frame.
* Visibility of Frames:: Frames may be visible or invisible, or icons.
* Raising and Lowering:: Raising a frame makes it hide other X windows;
- lowering it makes the others hide them.
+ lowering it puts it underneath the others.
* Frame Configurations:: Saving the state of all frames.
* Mouse Tracking:: Getting events that say when the mouse moves.
* Mouse Position:: Asking where the mouse is, or moving it.
* Pop-Up Menus:: Displaying a menu for the user to select from.
* Dialog Boxes:: Displaying a box to ask yes or no.
* Pointer Shapes:: Specifying the shape of the mouse pointer.
-* Window System Selections::Transferring text to and from other X clients.
+* Window System Selections::Transferring text to and from other window.
* Color Names:: Getting the definitions of color names.
* Resources:: Getting resource values from the server.
* Server Data:: Getting info about the X server.
@xref{Read Only Buffers}.
@item cyclic-function-indirection
-@code{"Symbol's chain of function indirections contains a loop"}@*
+@code{"Symbol's chain of function indirections@* contains a loop"}@*
@xref{Function Indirection}.
@item end-of-buffer
* Pointer Shapes:: Specifying the shape of the mouse pointer.
* Window System Selections:: Transferring text to and from other X clients.
* Font Names:: Looking up font names.
+* Fontsets:: A fontset is a collection of fonts
+ for displaying various character sets.
* Color Names:: Getting the definitions of color names.
* Resources:: Getting resource values from the server.
* Server Data:: Getting info about the X server.
@end menu
- @xref{Display}, for related information.
+ @xref{Display}, for information about the related topic of
+controlling Emacs redisplay.
@node Creating Frames
@section Creating Frames
@node Multiple Displays
@section Multiple Displays
-@cindex multiple displays
-@cindex multiple X terminals
+@cindex multiple X displays
@cindex displays, multiple
- A single Emacs can talk to more than one X Window display.
+ A single Emacs can talk to more than one X display.
Initially, Emacs uses just one display---the one chosen with the
@code{DISPLAY} environment variable or with the @samp{--display} option
(@pxref{Initial Options,,, emacs, The GNU Emacs Manual}). To connect to
the @code{display} frame parameter when you create the frame.
Emacs treats each X server as a separate terminal, giving each one its
-own selected frame and its own minibuffer windows. A few Lisp variables
-have values local to the current terminal (that is, the terminal
-corresponding to the currently selected frame): these are
-@code{default-minibuffer-frame}, @code{defining-kbd-macro},
-@code{last-kbd-macro}, and @code{system-key-alist}. These variables are
-always terminal-local and can never be buffer-local or frame-local
-(@pxref{Buffer-Local Variables}).
+own selected frame and its own minibuffer windows.
+
+ A few Lisp variables are @dfn{terminal-local}; that is, they have a
+separate binding for each terminal. The binding in effect at any time
+is the one for the terminal that the currently selected frame belongs
+to. These variables include @code{default-minibuffer-frame},
+@code{defining-kbd-macro}, @code{last-kbd-macro}, and
+@code{system-key-alist}. They are always terminal-local, and can never
+be buffer-local (@pxref{Buffer-Local Variables}) or frame-local.
A single X server can handle more than one screen. A display name
-@samp{@var{host}.@var{server}.@var{screen}} has three parts; the last
+@samp{@var{host}:@var{server}.@var{screen}} has three parts; the last
part specifies the screen number for a given server. When you use two
screens belonging to one server, Emacs knows by the similarity in their
names that they share a single keyboard, and it treats them as a single
uses.
Frame parameters exist for the sake of window systems. A terminal frame
-has a few parameters, mostly for compatibility's sake; only the height,
-width, @code{name}, @code{title}, @code{buffer-list} and
+has a few parameters, mostly for compatibility's sake; only the @code{height},
+@code{width}, @code{name}, @code{title}, @code{buffer-list} and
@code{buffer-predicate} parameters do something special.
@menu
The color to use for the image of a character. This is a string; the
window system defines the meaningful color names.
+If you set the @code{foreground-color} frame parameter, you should
+call @code{frame-update-face-colors} to update faces accordingly.
+
@item background-color
The color to use for the background of characters.
+If you set the @code{background-color} frame parameter, you should
+call @code{frame-update-face-colors} to update faces accordingly.
+@xref{Face Functions}.
+
+@item background-mode
+This parameter is either @code{dark} or @code{light}, according
+to whether the background color is a light one or a dark one.
+
@item mouse-color
The color for the mouse pointer.
@item border-color
The color for the border of the frame.
+@item display-type
+This parameter describes the range of possible colors that can be used
+in this frame. Its value is @code{color}, @code{grayscale} or
+@code{mono}.
+
@item cursor-type
The way to display the cursor. The legitimate values are @code{bar},
@code{box}, and @code{(bar . @var{width})}. The symbol @code{box}
@node Size and Position
@subsection Frame Size And Position
+@cindex size of frame
+@cindex screen size
+@cindex frame size
+@cindex resize frame
You can read or change the size and position of a frame using the
frame parameters @code{left}, @code{top}, @code{height}, and
@defun set-frame-position frame left top
This function sets the position of the top left corner of @var{frame} to
@var{left} and @var{top}. These arguments are measured in pixels, and
-count from the top left corner of the screen. Negative parameter values
-count up or rightward from the top left corner of the screen.
+normally count from the top left corner of the screen.
+
+Negative parameter values position the bottom edge of the window up from
+the bottom edge of the screen, or the right window edge to the left of
+the right edge of the screen. It would probably be better if the values
+were always counted from the left and top, so that negative arguments
+would position the frame partly off the top or left edge of the screen,
+but it seems inadvisable to change that now.
@end defun
@defun frame-height &optional frame
@defunx frame-width &optional frame
These functions return the height and width of @var{frame}, measured in
-characters. If you don't supply @var{frame}, they use the selected
-frame.
+lines and columns. If you don't supply @var{frame}, they use the
+selected frame.
+@end defun
+
+@defun screen-height
+@defunx screen-width
+These functions are old aliases for @code{frame-height} and
+@code{frame-width}. When you are using a non-window terminal, the size
+of the frame is normally the same as the size of the terminal screen.
@end defun
@defun frame-pixel-height &optional frame
them to units of characters.
@end defun
+@defun set-frame-height frame lines &optional pretend
+This function resizes @var{frame} to a height of @var{lines} lines. The
+sizes of existing windows in @var{frame} are altered proportionally to
+fit.
+
+If @var{pretend} is non-@code{nil}, then Emacs displays @var{lines}
+lines of output in @var{frame}, but does not change its value for the
+actual height of the frame. This is only useful for a terminal frame.
+Using a smaller height than the terminal actually implements may be
+useful to reproduce behavior observed on a smaller screen, or if the
+terminal malfunctions when using its whole screen. Setting the frame
+height ``for real'' does not always work, because knowing the correct
+actual size may be necessary for correct cursor positioning on a
+terminal frame.
+@end defun
+
+@defun set-frame-width frame width &optional pretend
+This function sets the width of @var{frame}, measured in characters.
+The argument @var{pretend} has the same meaning as in
+@code{set-frame-height}.
+@end defun
+
+@findex set-screen-height
+@findex set-screen-width
The old-fashioned functions @code{set-screen-height} and
@code{set-screen-width}, which were used to specify the height and width
of the screen in Emacs versions that did not support multiple frames,
-are still usable. They apply to the selected frame. @xref{Screen
-Size}.
+are still usable. They apply to the selected frame.
@defun x-parse-geometry geom
@cindex geometry specification
-The function @code{x-parse-geometry} converts a standard X Windows
+The function @code{x-parse-geometry} converts a standard X window
geometry string to an alist that you can use as part of the argument to
@code{make-frame}.
@example
(x-parse-geometry "35x70+0-0")
- @result{} ((width . 35) (height . 70)
- (left . 0) (top - 0))
+ @result{} ((height . 70) (width . 35)
+ (top - 0) (left . 0))
@end example
@end defun
-@ignore
-New functions @code{set-frame-height} and @code{set-frame-width} set the
-size of a specified frame. The frame is the first argument; the size is
-the second.
-@end ignore
-
@node Frame Titles
@section Frame Titles
to switch frames, and the change lasts until overridden by a subsequent
call to @code{switch-frame}. Each terminal screen except for the
initial one has a number, and the number of the selected frame appears
-in the mode line after the word @samp{Emacs} (@pxref{Mode Line
-Variables}).
+in the mode line before the buffer name (@pxref{Mode Line Variables}).
@c ??? This is not yet implemented properly.
@defun select-frame frame
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
+@defun create-fontset-from-fontset-spec fontset-spec &optional style-variant-p noerror
This function defines a new fontset according to the specification
string @var{fontset-spec}. The string should have this format:
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
+The new 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.
+If optional argument @var{style-variant-p} is non-@code{nil}, that says
+to create bold, italic and bold-italic variants of the fontset as well.
+These variant fontsets do not have a short name, only a long one, which
+is made by altering @var{fontpattern} to indicate the bold or italic
+status.
+
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
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
+have @samp{song ti} or @samp{fangsong ti} in the @var{family} field. In
such a case, @samp{Fontset-@var{n}} can be specified as below:
@smallexample
@end example
The color values are returned for @var{frame}'s display. If @var{frame}
-is omitted or @code{nil}, the information is return for the selected
+is omitted or @code{nil}, the information is returned for the selected
frame's display.
@end defun
@c Wordy to prevent overfull hbox. --rjc 15mar92
The @file{emacs/lib-src} directory contains two utilities that you can
use to print nice-looking hardcopy for the file
-@file{emacs/etc/DOC-@var{version}}. These are @file{sorted-doc.c} and
-@file{digest-doc.c}.
+@file{emacs/etc/DOC-@var{version}}. These are @file{sorted-doc} and
+@file{digest-doc}.
@node Accessing Documentation
@section Access to Documentation Strings
@defun documentation-property symbol property &optional verbatim
This function returns the documentation string that is recorded
-@var{symbol}'s property list under property @var{property}. It
+in @var{symbol}'s property list under property @var{property}. It
retrieves the text from a file if necessary, and runs
@code{substitute-command-keys} to substitute actual key bindings. (This
substitution is not done if @var{verbatim} is non-@code{nil}.)
@group
(documentation-property 'command-line-processed
'variable-documentation)
- @result{} "t once command line has been processed"
+ @result{} "Non-nil once command line has been processed"
@end group
@group
(symbol-plist 'command-line-processed)
@c That makes them incorrect.
@group
-set-goal-column Command: C-x C-n
+set-goal-column Keys: C-x C-n
Set the current horizontal position as a goal for C-n and C-p.
@end group
@c DO NOT put a blank line here! That is factually inaccurate!
@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
+Usually the value of @code{help-form} is @code{nil}. Then the
help character has no special meaning at the level of command input, and
it becomes part of a key sequence in the normal way. The standard key
binding of @kbd{C-h} is a prefix key for several general-purpose help
Emacs maintainers more quickly, send mail to
@code{bug-gnu-emacs@@gnu.org}.
-@display
- --Bil Lewis, Dan LaLiberte, Richard Stallman
-@end display
-
@node Lisp History
@section Lisp History
@cindex Lisp history
also stored in the variable @code{ctl-x-map}. This keymap defines
bindings for key sequences starting with @kbd{C-x}.
- Here is a list of the standard prefix keys of Emacs and their keymaps:
+ Some of the standard Emacs prefix keys use keymaps that are
+also found in Lisp variables:
@itemize @bullet
@item
This map is found via the function cell of the symbol
@code{Control-X-prefix}.
+@item
+@cindex @kbd{C-x @key{RET}}
+@vindex mule-keymap
+@code{mule-keymap} is the global keymap used for the @kbd{C-x @key{RET}}
+prefix key.
+
@item
@cindex @kbd{C-x 4}
@vindex ctl-x-4-map
@c Emacs 19 feature
@item
-@cindex @kbd{C-x n}
-@cindex @kbd{C-x r}
-@cindex @kbd{C-x a}
-The prefix keys @kbd{C-x n}, @kbd{C-x r} and @kbd{C-x a} use keymaps
-that have no special names.
+@cindex @kbd{C-x 6}
+@vindex 2C-mode-map
+@code{2C-mode-map} is the global keymap used for the @kbd{C-x 6} prefix
+key.
+
+@item
+@cindex @kbd{C-x v}
+@vindex vc-prefix-map
+@code{vc-prefix-map} is the global keymap used for the @kbd{C-x v} prefix
+key.
+
+@item
+@cindex @kbd{M-g}
+@vindex facemenu-keymap
+@code{facemenu-keymap} is the global keymap used for the @kbd{M-g}
+prefix key.
+
+@c Emacs 19 feature
+@item
+The other Emacs prefix keys are @kbd{C-x @@}, @kbd{C-x a i}, @kbd{C-x
+@key{ESC}} and @kbd{@key{ESC} @key{ESC}}. They use keymaps that have no
+special names.
@end itemize
The keymap binding of a prefix key is used for looking up the event
elements of @code{minor-mode-map-alist}: @code{(@var{variable}
. @var{keymap})}.
-If a variable appears an element of
+If a variable appears as 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}.
@smallexample
@group
- @dots{}
- (setq dired-mode-map (make-keymap))
- (suppress-keymap dired-mode-map)
- (define-key dired-mode-map "r" 'dired-rename-file)
- (define-key dired-mode-map "\C-d" 'dired-flag-file-deleted)
- (define-key dired-mode-map "d" 'dired-flag-file-deleted)
- (define-key dired-mode-map "v" 'dired-view-file)
- (define-key dired-mode-map "e" 'dired-find-file)
- (define-key dired-mode-map "f" 'dired-find-file)
- @dots{}
+(setq dired-mode-map (make-keymap))
+(suppress-keymap dired-mode-map)
+(define-key dired-mode-map "r" 'dired-rename-file)
+(define-key dired-mode-map "\C-d" 'dired-flag-file-deleted)
+(define-key dired-mode-map "d" 'dired-flag-file-deleted)
+(define-key dired-mode-map "v" 'dired-view-file)
+(define-key dired-mode-map "e" 'dired-find-file)
+(define-key dired-mode-map "f" 'dired-find-file)
+@dots{}
@end group
@end smallexample
@end defun
functions should use @code{read}.
@end defvar
- For how @code{load} is used to build Emacs, see @ref{Building Emacs}.
+ For information about how @code{load} is used in building Emacs, see
+@ref{Building Emacs}.
@node Library Search
@section Library Search
Here is an example of how to set your @code{EMACSLOADPATH} variable from
a @code{csh} @file{.login} file:
-@c This overfull hbox is OK. --rjc 16mar92
@smallexample
-setenv EMACSLOADPATH .:/user/bil/emacs:/usr/local/lib/emacs/lisp
+setenv EMACSLOADPATH .:/user/bil/emacs:/usr/local/lib/emacs/20.3/lisp
@end smallexample
Here is how to set it using @code{sh}:
@smallexample
export EMACSLOADPATH
-EMACSLOADPATH=.:/user/bil/emacs:/usr/local/lib/emacs/lisp
+EMACSLOADPATH=.:/user/bil/emacs:/usr/local/lib/emacs/20.3/lisp
@end smallexample
Here is an example of code you can place in a @file{.emacs} file to add
@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.
+@var{type}. If @var{type} is @code{t}, @var{marker} will advance when
+text is inserted at its position. If @var{type} is @code{nil},
+@var{marker} does not advance when text is inserted there.
@end defun
@defun marker-insertion-type marker
to minibuffers. The name of a minibuffer always has the form @w{@samp{
*Minibuf-@var{number}}}, and it cannot be changed. Minibuffers are
displayed only in special windows used only for minibuffers; these
-windows always appear at the bottom of a frame. (Sometime frames have
+windows always appear at the bottom of a frame. (Sometimes frames have
no minibuffer window, and sometimes a special kind of frame contains
nothing but a minibuffer window; see @ref{Minibuffers and Frames}.)
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 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.
+minibuffer inherits the current 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
@end defun
@defvar minibuffer-allow-text-properties
-If this variable is non-@code{nil}, then @code{read-from-minibuffer}
-strips all text properties from the string before returning the string.
+If this variable is @code{nil}, then @code{read-from-minibuffer} strips
+all text properties from the minibuffer input before returning it.
Since all minibuffer input uses @code{read-from-minibuffer}, this
variable applies to all minibuffer input.
+
+Note that the completion functions discard text properties unconditionally,
+regardless of the value of this variable.
@end defvar
@defvar minibuffer-local-map
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 buffer's input method (@pxref{Input
+minibuffer inherits the current 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.
@end defun
See also the functions @code{read-coding-system} and
-@code{read-non-nil-coding-system}, in @ref{Lisp and Coding Systems}.
+@code{read-non-nil-coding-system}, in @ref{User-Chosen Coding Systems}.
@node Reading File Names
@subsection Reading File Names
@c Emacs 19 feature
If you specify @var{initial}, that is an initial file name to insert in
-the buffer (after with @var{directory}, if that is inserted). In this
+the buffer (after @var{directory}, if that is inserted). In this
case, point goes at the beginning of @var{initial}. The default for
@var{initial} is @code{nil}---don't insert any file name. To see what
@var{initial} does, try the command @kbd{C-x C-v}. @strong{Note:} we
Rmail Edit mode offers an example of changing the major mode
temporarily for a buffer, so it can be edited in a different way (with
-ordinary Emacs commands rather than Rmail). In such cases, the
+ordinary Emacs commands rather than Rmail commands). In such cases, the
temporary major mode usually has a command to switch back to the
buffer's usual mode (Rmail mode, in this case). You might be tempted to
present the temporary redefinitions inside a recursive edit and restore
Make a variable whose name ends in @samp{-mode} to control the minor
mode. We call this the @dfn{mode variable}. The minor mode command
should set this variable (@code{nil} to disable; anything else to
-enable.)
+enable).
If it is possible, implement the mode so that setting the variable
automatically enables or disables the mode. Then the minor mode command
-does not need to do anything except the variable.
+does not need to do anything except set the variable.
This variable is used in conjunction with the @code{minor-mode-alist} to
display the minor mode name in the mode line. It can also enable
@end smallexample
@end itemize
+ You can also use @code{add-to-list} to add an element to this list
+just once (@pxref{Setting Variables}).
+
@node Keymaps and Minor Modes
@subsection Keymaps and Minor Modes
@end group
@end example
+@noindent
+(The variables @code{line-number-mode}, @code{column-number-mode}
+and @code{which-func-mode} enable particular minor modes; as usual,
+these variable names are also the minor mode command names.)
+
@node Mode Line Variables
@subsection Variables Used in the Mode Line
@defvar mode-line-buffer-identification
This variable identifies the buffer being displayed in the window. Its
-default value is @code{("%12b")}, which means that it usually
-displays @samp{Emacs:} followed by seventeen characters of the buffer
-name. (In a terminal frame, it displays the frame name instead of
-@samp{Emacs}; this has the effect of showing the frame number.) You may
-want to change this in modes such as Rmail that do not behave like a
-``normal'' Emacs.
+default value is @code{("%12b")}, which means that it usually displays
+twelve characters of the buffer name.
@end defvar
@defvar global-mode-string
status in modes used for communicating with subprocesses. It is
displayed immediately following the major mode name, with no intervening
space. For example, its value in the @samp{*shell*} buffer is
-@code{(":@: %s")}, which allows the shell to display its status along
+@code{(":%s")}, which allows the shell to display its status along
with the major mode as: @samp{(Shell:@: run)}. Normally this variable
is @code{nil}.
@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:
+processing @code{imenu-generic-expression}, to override the syntax table
+of the current buffer. Each element should have this form:
@example
(@var{characters} . @var{syntax-description})
@end example
The @code{imenu-generic-expression} patterns can then use @samp{\\sw+}
-instead of @samp{\\(\\sw\\|\\s_\\)\\}. Note that this technique may be
+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
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.
+@var{args}, until some hook function returns @code{nil}. Then it stops,
+and returns @code{nil} if some hook function did, and otherwise
+returns a non-@code{nil} value.
@end defun
@defun run-hook-with-args-until-success hook &rest args
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.
+stops, and returns whatever was returned by the last hook function
+that was called.
@end defun
@defun add-hook hook function &optional append local
@cindex leading code
@cindex multibyte text
+@cindex trailing codes
In multibyte representation, a character may occupy more than one
byte, and as a result, the full range of Emacs character codes can be
stored. The first byte of a multibyte character is always in the range
128 through 159 (octal 0200 through 0237). These values are called
@dfn{leading codes}. The second and subsequent bytes of a multibyte
character are always in the range 160 through 255 (octal 0240 through
-0377).
+0377); these values are @dfn{trailing codes}.
In a buffer, the buffer-local value of the variable
@code{enable-multibyte-characters} specifies the representation used.
@defun string-make-unibyte string
@tindex string-make-unibyte
This function converts the text of @var{string} to unibyte
-representation, if it isn't already, and return the result. If
+representation, if it isn't already, and returns the result. If
@var{string} is a unibyte string, it is returned unchanged.
@end defun
@defun string-make-multibyte string
@tindex string-make-multibyte
This function converts the text of @var{string} to multibyte
-representation, if it isn't already, and return the result. If
+representation, if it isn't already, and returns the result. If
@var{string} is a multibyte string, it is returned unchanged.
@end defun
@cindex dimension (of character set)
In multibyte representation, each character occupies one or more
bytes. Each character set has an @dfn{introduction sequence}, which is
-one or two bytes long. The introduction sequence is the beginning of
-the byte sequence for any character in the character set. (The
-@sc{ASCII} character set has a zero-length introduction sequence.) The
-rest of the character's bytes distinguish it from the other characters
-in the same character set. Depending on the character set, there are
-either one or two distinguishing bytes; the number of such bytes is
-called the @dfn{dimension} of the character set.
+normally one or two bytes long. (Exception: the @sc{ASCII} character
+set has a zero-length introduction sequence.) The introduction sequence
+is the beginning of the byte sequence for any character in the character
+set. The rest of the character's bytes distinguish it from the other
+characters in the same character set. Depending on the character set,
+there are either one or two distinguishing bytes; the number of such
+bytes is called the @dfn{dimension} of the character set.
@defun charset-dimension charset
@tindex charset-dimension
This function returns the dimension of @var{charset};
-At present, the dimension is always 1 or 2.
+at present, the dimension is always 1 or 2.
@end defun
This is the simplest way to determine the byte length of a character
* Coding System Basics::
* Encoding and I/O::
* Lisp and Coding Systems::
+* User-Chosen Coding Systems::
* Default Coding Systems::
* Specifying Coding Systems::
* Explicit Encoding::
@node Encoding and I/O
@subsection Encoding and I/O
- The principal purpose coding systems is for use in reading and
+ The principal purpose of coding systems is for use in reading and
writing files. The function @code{insert-file-contents} uses
a coding system for decoding the file data, and @code{write-region}
uses one to encode the buffer contents.
@defun coding-system-change-eol-conversion coding-system eol-type
@tindex coding-system-change-eol-conversion
This function returns a coding system which is like @var{coding-system}
-except for its in eol conversion, which is specified by @code{eol-type}.
+except for its eol conversion, which is specified by @code{eol-type}.
@var{eol-type} should be @code{unix}, @code{dos}, @code{mac}, or
@code{nil}. If it is @code{nil}, the returned coding system determines
the end-of-line conversion from the data.
@tindex detect-coding-string
This function is like @code{detect-coding-region} except that it
operates on the contents of @var{string} instead of bytes in the buffer.
+@end defun
+
+ @xref{Process Information}, for how to examine or set the coding
+systems used for I/O to a subprocess.
+
+@node User-Chosen Coding Systems
+@subsection User-Chosen Coding Systems
+
+@tindex select-safe-coding-system
+@defun select-safe-coding-system from to &optional preferred-coding-system
+This function selects a coding system for encoding the between
+@var{from} and @var{to}, asking the user to choose if necessary.
+
+The optional argument @var{preferred-coding-system} specifies a coding
+system try first. If it can handle the text in the specified region,
+then it is used. If this argument is omitted, the current buffer's
+value of @code{buffer-file-coding-system} is tried first.
+
+If the region contains some multibyte characters that the preferred
+coding system cannot encode, this function asks the user to choose from
+a list of coding systems which can encode the text, and returns the
+user's choice.
+
+One other kludgy feature: if @var{from} is a string, the string is the
+target text, and @var{to} is ignored.
@end defun
Here are two functions you can use to let the user specify a coding
@xref{Coding Systems}.
@end defun
- @xref{Process Information}, for how to examine or set the coding
-systems used for I/O to a subprocess.
-
@node Default Coding Systems
@subsection Default Coding Systems
This section describes variables that specify the default coding
system for certain files or when running certain subprograms, and the
-function which which I/O operations use to access them.
+function that I/O operations use to access them.
The idea of these variables is that you set them once and for all to the
defaults you want, and then do not change them again. To specify a
expression that matches certain file names. The element applies to file
names that match @var{pattern}.
-The @sc{cdr} of the element, @var{val}, should be either a coding
+The @sc{cdr} of the element, @var{coding}, should be either a coding
system, a cons cell containing two coding systems, or a function symbol.
If @var{val} is a coding system, that coding system is used for both
reading the file and writing it. If @var{val} is a cons cell containing
@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 processes
+with asynchronous subprocess output. This is because Emacs handles
asynchronous subprocess output in batches, as it arrives. If the coding
system leaves the character code conversion unspecified, or leaves the
end-of-line conversion unspecified, Emacs must try to detect the proper
suppress encoding for that @code{write-region} call by binding
@code{coding-system-for-write} to @code{no-conversion}.
+ Raw bytes sometimes contain overlong byte-sequences that look like a
+proper multibyte character plus extra bytes containing trailing codes.
+For most purposes, Emacs treats such a sequence in a buffer or string as
+a single character, and if you look at its character code, you get the
+value that corresponds to the multibyte character sequence---the extra
+bytes are disregarded. This behavior is not quite clean, but raw bytes
+are used only in limited places in Emacs, so as a practical matter
+problems can be avoided.
+
@defun encode-coding-region start end coding-system
@tindex encode-coding-region
This function encodes the text from @var{start} to @var{end} according
Each element defines one input method, and should have the form:
@example
-(@var{input-method} @var{language-env} @var{activate-func} @var{title} @var{description} @var{args}...)
+(@var{input-method} @var{language-env} @var{activate-func}
+ @var{title} @var{description} @var{args}...)
@end example
-Here @var{input-method} is the input method name, a string; @var{env} is
-another string, the name of the language environment this input method
-is recommended for. (That serves only for documentation purposes.)
+Here @var{input-method} is the input method name, a string;
+@var{language-env} is another string, the name of the language
+environment this input method is recommended for. (That serves only for
+documentation purposes.)
@var{title} is a string to display in the mode line while this method is
active. @var{description} is a string describing this method and what
@var{args}, if any, are passed as arguments to @var{activate-func}. All
told, the arguments to @var{activate-func} are @var{input-method} and
the @var{args}.
-@end defun
+@end defvar
* Getting Out:: How exiting works (permanent or temporary).
* System Environment:: Distinguish the name and kind of system.
* User Identification:: Finding the name and user id of the user.
+* Reading a Password:: Reading a password from the terminal.
* Time of Day:: Getting the current time.
* Time Conversion:: Converting a time from numeric form to a string, or
to calendrical data (or vice versa).
@defvar site-run-file
This variable specifies the site-customization file to load
before the user's init file. Its normal value is @code{"site-start"}.
+(The only way to change it with real effect is before dumping Emacs.)
@end defvar
If there is a great deal of code in your @file{.emacs} file, you
@end defopt
@defvar before-init-hook
-This normal hook is run, once, just before loading of all the init files
+This normal hook is run, once, just before loading all the init files
(the user's init file, @file{default.el}, and/or @file{site-start.el}).
+(The only way to change it with real effect is before dumping Emacs.)
@end defvar
@defvar after-init-hook
-This normal hook is run, once, just after loading of all the init files
+This normal hook is run, once, just after loading 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
system Emacs is operating on. Here is a table of the possible values:
@table @code
+@item alpha-vms
+VMS on the Alpha.
+
@item aix-v3
AIX.
@end defvar
@defun load-average &optional use-float
-This function returns the current 1-minute, 5-minute and 15-minute load
-averages in a list.
+This function returns the current 1-minute, 5-minute, and 15-minute load
+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.
+as floating point numbers and without multiplying by 100.
@example
@group
This function returns the effective @sc{uid} of the user.
@end defun
+@node Reading a Password
+@section Reading a Password
+@cindex passwords, reading
+
+ To read a password to pass to another program, you can use the
+function @code{read-passwd}.
+
+@tindex read-passwd
+@defun read-passwd prompt &optional confirm default
+This function reads a password, prompting with @var{prompt}. It does
+not echo the password as the user types it; instead, it echoes @samp{.}
+for each character in the password.
+
+The optional argument @var{confirm}, if non-@code{nil}, says to read the
+password twice and insist it must be the same both times. If it isn't
+the same, the user has to type it over and over until the last two
+times match.
+
+The optional argument @var{default} specifies the default password to
+return if the user enters empty input. If @var{default} is @code{nil},
+then @code{read-passwd} returns the null string in that case.
+@end defun
+
@node Time of Day
@section Time of Day
Emacs cannot run timers at any arbitrary point in a Lisp program; it
can run them only when Emacs could accept output from a subprocess:
namely, while waiting or inside certain primitive functions such as
-@code{sit-for} or @code{read-char} which @emph{can} wait. Therefore, a
+@code{sit-for} or @code{read-event} which @emph{can} wait. Therefore, a
timer's execution may be delayed if Emacs is busy. However, the time of
execution is very precise if Emacs is idle.
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. Valid formats include these two,
+Absolute times may be specified in a wide variety of formats; this
+function tries to accept all the commonly used date formats. Valid
+formats include these two,
@example
@var{year}-@var{month}-@var{day} @var{hour}:@var{min}:@var{sec} @var{timezone}
servers; those do no harm, as long as they don't conflict with the ones
used by the X server actually in use.
-The variable is always local to the current X terminal and cannot be
+The variable is always local to the current terminal, and cannot be
buffer-local. @xref{Multiple Displays}.
@end defvar
@code{C-s} and @kbd{C-q} for flow control. Therefore, the choice of
@kbd{C-s} and @kbd{C-q} as command characters for searching and quoting
was natural and uncontroversial. With so many commands needing key
-assignments. of course we assigned meanings to nearly all @sc{ASCII}
+assignments, of course we assigned meanings to nearly all @sc{ASCII}
control characters.
Later, some terminals were introduced which required these characters
@deffn Command forward-word count
This function moves point forward @var{count} words (or backward if
-@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}.
+@var{count} is negative). ``Moving one word'' means moving until point
+crosses a word-constituent character and then encounters a
+word-separator character (or the boundary of the accessible part of the
+buffer).
-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}.
+If it is possible to move @var{count} words, without being stopped by
+the buffer boundary (except perhaps after the last word), the value is
+@code{t}. Otherwise, the return value is @code{nil} and point stops
+at the buffer boundary.
In an interactive call, @var{count} is set to the numeric prefix
argument.
given set of characters. It examines the character following point,
then advances point if the character matches @var{character-set}. This
continues until it reaches a character that does not match. The
-function returns @code{nil}.
+function returns the number of characters moved over.
The argument @var{character-set} is like the inside of a
@samp{[@dots{}]} in a regular expression except that @samp{]} is never
This function moves point backward, skipping characters that match
@var{character-set}, until @var{limit}. It is just like
@code{skip-chars-forward} except for the direction of motion.
+
+The return value indicates the distance traveled. It is an integer that
+is zero or less.
@end defun
@node Excursions
@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.
+before the inserted text.
Although @code{save-excursion} saves the location of the mark, it does
not prevent functions which modify the buffer from setting
Each of the subprocess-creating functions has a @var{buffer-or-name}
argument which specifies where the standard output from the program will
-go. It should be a buffer or a buffer name (which will create the
-buffer if it does not already exist). It can also be @code{nil}, which
-says to discard the output unless a filter function handles it.
-(@xref{Filter Functions}, and @ref{Read and Print}.) Normally, you
-should avoid having multiple processes send output to the same buffer
-because their output would be intermixed randomly.
+go. It should be a buffer or a buffer name; if it is a buffer name,
+that will create the buffer if it does not already exist. It can also
+be @code{nil}, which says to discard the output unless a filter function
+handles it. (@xref{Filter Functions}, and @ref{Read and Print}.)
+Normally, you should avoid having multiple processes send output to the
+same buffer because their output would be intermixed randomly.
@cindex program arguments
All three of the subprocess-creating functions have a @code{&rest}
@code{default-directory} (@pxref{File Name Expansion}).
@cindex environment variables, subprocesses
- The subprocess inherits its environment from Emacs; but you can
+ The subprocess inherits its environment from Emacs, but you can
specify overrides for it with @code{process-environment}. @xref{System
Environment}.
@defvar exec-directory
@pindex movemail
The value of this variable is the name of a directory (a string) that
-contains programs that come with GNU Emacs, that are intended for Emacs
+contains programs that come with GNU Emacs, programs intended for Emacs
to invoke. The program @code{movemail} is an example of such a program;
Rmail uses it to fetch new mail from an inbox.
@end defvar
Emacs is essentially finished with the subprocess as soon as this
function returns.
-@item (@var{real-destination} @var{error-destination})
+@item @code{(@var{real-destination} @var{error-destination})}
Keep the standard output stream separate from the standard error stream;
deal with the ordinary output as specified by @var{real-destination},
and dispose of the error output according to @var{error-destination}.
@section Creating an Asynchronous Process
@cindex asynchronous subprocess
- After an @dfn{asynchronous process} is created, Emacs and the Lisp
-program both continue running immediately. The process thereafter runs
+ After an @dfn{asynchronous process} is created, Emacs and the subprocess
+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
away. If you delete a terminated process explicitly before it is
deleted automatically, no harm results.
-@defvar delete-exited-processes
+@defopt delete-exited-processes
This variable controls automatic deletion of processes that have
terminated (due to calling @code{exit} or to a signal). If it is
@code{nil}, then they continue to exist until the user runs
@code{list-processes}. Otherwise, they are deleted immediately after
they exit.
-@end defvar
+@end defopt
@defun delete-process name
This function deletes the process associated with @var{name}, killing it
@end smallexample
@end defun
-@defun process-kill-without-query process
-This function declares that Emacs need not query the user if
-@var{process} is still running when Emacs is exited. The process will
-be deleted silently. The value is @code{t}.
+@defun process-kill-without-query process &optional do-query
+This function specifies whether Emacs should query the user if
+@var{process} is still running when Emacs is exited. If @var{do-query}
+is @code{nil}, the process will be deleted silently.
+Otherwise, Emacs will query about killing it.
+
+The value is @code{t} if the process was formerly set up to require
+query. @code{nil} otherwise. A newly-created process always requires
+query.
@smallexample
@group
The argument @var{seconds} need not be an integer. If it is a floating
point number, this function waits for a fractional number of seconds.
Some systems support only a whole number of seconds; on these systems,
-@var{seconds} is rounded down. If the system doesn't support waiting
-fractions of a second, you get an error if you specify nonzero
-@var{millisec}.
+@var{seconds} is rounded down.
Not all operating systems support waiting periods other than multiples
of a second; on those that do not, you get an error if you specify
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
+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.
You can also include character ranges in a character alternative, by
writing the starting and ending characters with a @samp{-} between them.
-Thus, @samp{[a-z]} matches any lower-case ASCII letter. Ranges may be
+Thus, @samp{[a-z]} matches any lower-case @sc{ASCII} letter. Ranges may be
intermixed freely with individual characters, as in @samp{[a-z$%.]},
-which matches any lower case ASCII letter or @samp{$}, @samp{%} or
+which matches any lower case @sc{ASCII} letter or @samp{$}, @samp{%} or
period.
You cannot always match all non-@sc{ASCII} characters with the regular
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 Emacs character set for Latin-1.
+(@pxref{Character Sets}). Thus, @samp{[a-\x8e0]} is invalid because
+@samp{a} is in the @sc{ASCII} character set but the character 0x8e0
+(@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
You can save and restore the match data with @code{save-match-data}:
@defmac save-match-data body@dots{}
-This special form executes @var{body}, saving and restoring the match
+This macro executes @var{body}, saving and restoring the match
data around it.
@end defmac
@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
+This function sets the value in @var{char-table} for a range of
characters @var{range}. Here are the possibilities for @var{range}:
@table @asis
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))
+(let (accumulator)
+ (map-char-table
+ #'(lambda (key value)
+ (setq accumulator
+ (cons (list key value) accumulator)))
+ (syntax-table))
+ accumulator)
@result{}
((475008 nil) (474880 nil) (474752 nil) (474624 nil)
... (5 (3)) (4 (3)) (3 (3)) (2 (3)) (1 (3)) (0 (3)))
@cindex print example
@example
-@group
-(setq m (set-marker (make-marker) 10 (get-buffer "foo")))
- @result{} #<marker at 10 in foo>
-@end group
-
@group
---------- Buffer: foo ----------
This is t@point{}he contents of foo.
(print "This is the output" (get-buffer "foo"))
@result{} "This is the output"
-@group
-m
- @result{} #<marker at 32 in foo>
-@end group
@group
---------- Buffer: foo ----------
This is t
@end group
@group
-m
- @result{} #<marker at 11 in foo>
+(setq m (copy-marker 10))
+ @result{} #<marker at 10 in foo>
@end group
@group
@group
m
- @result{} #<marker at 35 in foo>
+ @result{} #<marker at 34 in foo>
@end group
@end example
@code{prin1}, but not during the printing of the result.
@end defvar
+@tindex print-escape-nonascii
+@defvar print-escape-nonascii
+If this variable is non-@code{nil}, then unibyte non-@sc{ASCII}
+characters in strings are unconditionally printed as backslash sequences
+by the print functions @code{prin1} and @code{print} that print with
+quoting.
+@end defvar
+
@defvar print-length
@cindex printing limits
The value of this variable is the maximum number of elements to print in
@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.
+(@pxref{Text Representations}) so that a unibyte string can be equal to
+a multibyte string. If @var{ignore-case} is non-@code{nil}, then case
+is ignored, so that upper case letters can be equal to lower case letters.
If the specified portions of the two strings match, the value is
@code{t}. Otherwise, the value is an integer which indicates how many
@item @samp{*/}
This is a comment-end sequence for ``a'' style because the first
-character, @samp{*}, does not have the @samp{b} flag
+character, @samp{*}, does not have the @samp{b} flag.
@item newline
This is a comment-end sequence for ``b'' style, because the newline
mentioned in @var{syntaxes}. It stops when it encounters the end of
the buffer, or position @var{limit} (if specified), or a character it is
not supposed to skip.
-@ignore @c may want to change this.
The return value is the distance traveled, which is a nonnegative
integer.
-@end ignore
@end defun
@defun skip-syntax-backward syntaxes &optional limit
classes are mentioned in @var{syntaxes}. It stops when it encounters
the beginning of the buffer, or position @var{limit} (if specified), or a
character it is not supposed to skip.
-@ignore @c may want to change this.
+
The return value indicates the distance traveled. It is an integer that
is zero or less.
-@end ignore
@end defun
@defun backward-prefix-chars
@var{stop-comment} is non-@code{nil}, parsing stops when it comes to the
start of a comment. If @var{stop-comment} is the symbol
@code{syntax-table}, parsing stops after the start of a comment or a
-string, or the of a comment or a string, whichever comes first.
+string, or the end of a comment or a string, whichever comes first.
@cindex parse state
The fifth argument @var{state} is a nine-element list of the same form
@defun get-unused-category table
This function returns a category name (a character) which is not
currently defined in @var{table}. If all possible categories are in use
-in @var{table}, it returns @code{nil},
+in @var{table}, it returns @code{nil}.
@end defun
@defun category-table
How to control how much information is kept.
* Filling:: Functions for explicit filling.
* Margins:: How to specify margins for filling commands.
+* Adaptive Fill: Adaptive Fill mode chooses a fill prefix from context.
* Auto Filling:: How auto-fill mode is implemented to break lines.
* Sorting:: Functions for sorting parts of the buffer.
* Columns:: Computing horizontal positions, and using them.
Several simple functions are described here. See also @code{looking-at}
in @ref{Regexp Search}.
-@defun char-after position
+@defun char-after &optional position
This function returns the character in the current buffer at (i.e.,
immediately after) position @var{position}. If @var{position} is out of
range for this purpose, either before the beginning of the buffer, or at
-or beyond the end, then the value is @code{nil}.
+or beyond the end, then the value is @code{nil}. The default for
+@var{position} is point.
In the following example, assume that the first character in the
buffer is @samp{@@}:
@end example
@end defun
-@defun char-before position
+@defun char-before &optional position
This function returns the character in the current buffer immediately
before position @var{position}. If @var{position} is out of range for
this purpose, either before the beginning of the buffer, or at or beyond
-the end, then the value is @code{nil}.
+the end, then the value is @code{nil}. The default for
+@var{position} is point.
@end defun
@defun following-char
@end deffn
@defvar overwrite-mode
-This variable controls whether overwrite mode is in effect: a
-non-@code{nil} value enables the mode. It is automatically made
-buffer-local when set in any fashion.
+This variable controls whether overwrite mode is in effect. The value
+should be @code{overwrite-mode-textual}, @code{overwrite-mode-binary},
+or @code{nil}. @code{overwrite-mode-textual} specifies textual
+overwrite mode (treats newlines and tabs specially), and
+@code{overwrite-mode-binary} specifies binary overwrite mode (treats
+newlines and tabs like any other characters).
@end defvar
@node Deletion
All of the deletion functions operate on the current buffer, and all
return a value of @code{nil}.
-@defun erase-buffer
+@deffn Command erase-buffer
This function deletes the entire text of the current buffer, leaving it
empty. If the buffer is read-only, it signals a @code{buffer-read-only}
error. Otherwise, it deletes the text without asking for any
@code{erase-buffer} does not do this, the idea being that the future
text is not really related to the former text, and its size should not
be compared with that of the former text.
-@end defun
+@end deffn
@deffn Command delete-region start end
This command deletes the text in the current buffer in the region
text into the kill ring from a read-only buffer.
@end deffn
+@defopt kill-read-only-ok
+If this option is non-@code{nil}, @code{kill-region} does not get an
+error if the buffer is read-only. Instead, it simply returns, updating
+the kill ring but not changing the buffer.
+@end defopt
+
@deffn Command copy-region-as-kill start end
This command saves the region defined by @var{start} and @var{end} on
the kill ring (including text properties), but does not delete the text
Here are the kinds of elements an undo list can have:
@table @code
-@item @var{integer}
-This kind of element records a previous value of point. Ordinary cursor
-motion does not get any sort of undo record, but deletion operations use
-these entries to record where point was before the command.
+@item @var{position}
+This kind of element records a previous value of point; undoing this
+element moves point to @var{position}. Ordinary cursor motion does not
+make any sort of undo record, but deletion operations use these entries
+to record where point was before the command.
@item (@var{beg} . @var{end})
This kind of element indicates how to delete text that was inserted.
@var{adjustment} character positions. Undoing this element moves
@var{marker} @minus{} @var{adjustment} characters.
-@item @var{position}
-This element indicates where point was at an earlier time. Undoing this
-element sets point to @var{position}. Deletion normally creates an
-element of this kind as well as a reinsertion element.
-
@item nil
This element is a boundary. The elements between two boundaries are
called a @dfn{change group}; normally, each change group corresponds to
boundaries. @xref{Paragraphs,,, emacs, The Emacs Manual}.
@end deffn
-@deffn Command fill-region start end &optional justify
+@deffn Command fill-region start end &optional justify nosqueeze
This command fills each of the paragraphs in the region from @var{start}
to @var{end}. It justifies as well if @var{justify} is
non-@code{nil}.
+If @var{nosqueeze} is non-@code{nil}, that means to leave whitespace
+other than line breaks untouched. If @var{to-eop} is non-@code{nil},
+that means to keep filling to the end of the paragraph---or next hard
+newline, if @code{use-hard-newlines} is enabled (see below).
+
The variable @code{paragraph-separate} controls how to distinguish
paragraphs. @xref{Standard Regexps}.
@end deffn
described above.
@end defopt
-@deffn Command fill-region-as-paragraph start end &optional justify
+@deffn Command fill-region-as-paragraph start end &optional justify nosqueeze squeeze-after
This command considers a region of text as a single paragraph and fills
it. If the region was made up of many paragraphs, the blank lines
between paragraphs are removed. This function justifies as well as
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
-as the fill prefix.
+If @var{nosqueeze} is non-@code{nil}, that means to leave whitespace
+other than line breaks untouched. If @var{squeeze-after} is
+non-@code{nil}, specifies a position in the region, and means don't
+canonicalize spaces before that position.
+
+In Adaptive Fill mode, this command calls @code{fill-context-prefix} to
+choose a fill prefix by default. @xref{Adaptive Fill}.
@end deffn
@deffn Command justify-current-line how eop nosqueeze
the text around point.
@end defun
+@defopt sentence-end-double-space
+If this variable is non-@code{nil}, a period followed by just one space
+does not count as the end of a sentence, and the filling functions
+avoid breaking the line at such a place.
+@end defopt
+
@defvar fill-paragraph-function
This variable provides a way for major modes to override the filling of
paragraphs. If the value is non-@code{nil}, @code{fill-paragraph} calls
The fill prefix follows the left margin whitespace, if any.
@end defopt
-@defvar fill-column
+@defopt 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
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 defvar
+@end defopt
@defvar default-fill-column
The value of this variable is the default value for @code{fill-column} in
non-@code{nil}, then the line won't be broken there.
@end defvar
+@node Adaptive Fill
+@section Adaptive Fill Mode
+@cindex Adaptive Fill mode
+
+ Adaptive Fill mode chooses a fill prefix automatically from the text
+in each paragraph being filled.
+
+@defopt adaptive-fill-mode
+Adaptive Fill mode is enabled when this variable is non-@code{nil}.
+It is @code{t} by default.
+@end defopt
+
+@defun fill-context-prefix from to
+This function implements the heart of Adaptive Fill mode; it chooses a
+fill prefix based on the text between @var{from} and @var{to}. It does
+this by looking at the first two lines of the paragraph, based on the
+variables described below.
+@end defun
+
+@defopt adaptive-fill-regexp
+This variable holds a regular expression to control Adaptive Fill mode.
+Whichever characters starting after the line's left margin match this
+regular expression, those are the candidate for the fill prefix.
+@end defopt
+
+@defopt adaptive-fill-first-line-regexp
+In a one-line paragraph, if the candidate fill prefix matches
+this regular expression, or if it matches @code{comment-start-skip},
+then it is used---otherwise, it is replaced with an equivalent
+number of spaces.
+
+However, the fill prefix is never taken from a one-line paragraph
+if it would act as a paragraph starter on subsequent lines.
+@end defopt
+
+@defopt adaptive-fill-function
+You can specify more complex ways of choosing a fill prefix
+automatically by setting this variable to a function. The function is
+called when @code{adaptive-fill-regexp} does not match, with point after
+the left margin of a line, and it should return the appropriate fill
+prefix based on that line. If it returns @code{nil}, that means it sees
+no fill prefix in that line.
+@end defopt
+
@node Auto Filling
@comment node-name, next, previous, up
@section Auto Filling
@end group
@group
(interactive "P\nr")
- (save-restriction
- (narrow-to-region beg end)
- (goto-char (point-min))
- (sort-subr reverse 'forward-line 'end-of-line)))
+ (save-excursion
+ (save-restriction
+ (narrow-to-region beg end)
+ (goto-char (point-min))
+ (sort-subr reverse 'forward-line 'end-of-line))))
@end group
@end example
@example
@group
(sort-subr reverse
- (function
- (lambda () (skip-chars-forward "\n \t\f")))
+ (function
+ (lambda ()
+ (while (and (not (eobp))
+ (looking-at paragraph-separate))
+ (forward-line 1))))
'forward-paragraph)
@end group
@end example
position after @code{sort-subr} returns.
@end defun
+@defopt sort-fold-case
+If this variable is non-@code{nil}, @code{sort-subr} and the other
+buffer sorting functions ignore case when comparing strings.
+@end defopt
+
@deffn Command sort-regexp-fields reverse record-regexp key-regexp start end
This command sorts the region between @var{start} and @var{end}
alphabetically as specified by @var{record-regexp} and @var{key-regexp}.
@deffn Command reindent-then-newline-and-indent
@comment !!SourceFile simple.el
This command reindents the current line, inserts a newline at point,
-and then reindents the new line (the one following the newline just
+and then indents the new line (the one following the newline just
inserted).
This command does indentation on both lines according to the current
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 the difference between the buffer positions
+The length of the old text is 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 example
@item
-If calling a small function accounts for a substantial part of your
+If calling a small function accounts for a substantial part of your
program's running time, make the function inline. This eliminates
the function call overhead. Since making a function inline reduces
the flexibility of changing the program, don't do it unless it gives
@item
For consistency, phrase the verb in the first sentence of a
-documentation string as an infinitive with ``to'' omitted. For
+function's documentation string as an infinitive with ``to'' omitted. For
instance, use ``Return the cons of A and B.'' in preference to ``Returns
the cons of A and B@.'' Usually it looks good to do likewise for the
rest of the first paragraph. Subsequent paragraphs usually look better
convention, with single-quotes for all symbols.)
@end ifinfo
-Help mode automatically creates hyperlinks when documentation strings
-use symbol names inside single quotes, when the symbol has either a
+Help mode automatically creates a hyperlink when a documentation string
+uses a symbol name inside single quotes, if 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
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 each X terminal; see
+variables have bindings that are local to each terminal; see
@ref{Multiple Displays}.)
@menu
@end deffn
@deffn Command split-window-vertically size
-This function splits the selected window into two windows, one above
-the other, leaving the selected window with @var{size} lines.
+This function splits the selected window into two windows, one above the
+other, leaving the upper of the two window selected, with @var{size}
+lines. (If @var{size} is negative, then the lower of the two windows
+gets @minus{} @var{size} lines and the upper window gets the rest, but
+the upper window is still the one selected.)
-This function is simply an interface to @code{split-windows}.
+This function is simply an interface to @code{split-window}.
Here is the complete function definition for it:
@smallexample
This function splits the selected window into two windows
side-by-side, leaving the selected window with @var{size} columns.
-This function is simply an interface to @code{split-windows}. Here is
+This function is simply an interface to @code{split-window}. Here is
the complete definition for @code{split-window-horizontally} (except for
part of the documentation string):
single window showing another buffer chosen with @code{other-buffer}.
@xref{The Buffer List}.
-The argument @var{frame} controls which frames to operate on:
+The argument @var{frame} controls which frames to operate on. This
+function does not use it in quite the same way as the other functions
+which scan all windows; specifically, the values @code{t} and @code{nil}
+have the opposite of their meanings in other functions. Here are the
+full details:
@itemize @bullet
@item
-If it is @code{nil}, operate on the selected frame.
+If it is @code{nil}, operate on all frames.
@item
-If it is @code{t}, operate on all frames.
+If it is @code{t}, operate on the selected frame.
@item
If it is @code{visible}, operate on all visible frames.
-@item 0
+@item
If it is 0, operate on all visible or iconified frames.
@item
If it is a frame, operate on that frame.
the window that is first in the cyclic ordering of windows (see
following section), starting from the selected window.
-The argument @var{frame} controls which set of windows are
-considered. See @code{get-lru-window}, above.
+The argument @var{frame} controls which set of windows to
+consider. See @code{get-lru-window}, above.
@end defun
@node Cyclic Window Ordering
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
+When a buffer is first created, @code{buffer-display-time} starts out
with the value @code{nil}.
@end defvar
current so that a Lisp program can access or modify it; they are too
drastic for that purpose, since they change the display of buffers in
windows, which would be gratuitous and surprise the user. Instead, use
-@code{set-buffer} (@pxref{Current Buffer}) and @code{save-excursion}
-(@pxref{Excursions}), which designate buffers as current for programmed
-access without affecting the display of buffers in windows.
+@code{set-buffer} and @code{save-current-buffer} (@pxref{Current
+Buffer}), which designate buffers as current for programmed access
+without affecting the display of buffers in windows.
@deffn Command switch-to-buffer buffer-or-name &optional norecord
This function makes @var{buffer-or-name} the current buffer, and also
@var{buffer-or-name}.
If the argument @var{frame} is non-@code{nil}, it specifies which frames
-to check when deciding whether the buffer is already displayed. Its
-value means the same thing as in functions @code{get-buffer-window}
-(@pxref{Buffers and Windows}). If the buffer is already displayed
-in some window on one of these frames, @code{display-buffer} simply
-returns that window.
+to check when deciding whether the buffer is already displayed. If the
+buffer is already displayed in some window on one of these frames,
+@code{display-buffer} simply returns that window. Here are the possible
+values of @var{frame}:
+
+@itemize @bullet
+@item
+If it is @code{nil}, consider windows on the selected frame.
+@item
+If it is @code{t}, consider windows on all frames.
+@item
+If it is @code{visible}, consider windows on all visible frames.
+@item
+If it is 0, consider windows on all visible or iconified frames.
+@item
+If it is a frame, consider windows on that frame.
+@end itemize
Precisely how @code{display-buffer} finds or creates a window depends on
the variables described below.
more information about frame parameters.
@end defvar
-@defvar special-display-buffer-names
+@defopt special-display-buffer-names
A list of buffer names for buffers that should be displayed specially.
If the buffer's name is in this list, @code{display-buffer} handles the
buffer specially.
an alist, specifying frame parameters, or it can contain a function and
arguments to give to it. (The function's first argument is always the
buffer to be displayed; the arguments from the list come after that.)
-@end defvar
+@end defopt
-@defvar special-display-regexps
+@defopt special-display-regexps
A list of regular expressions that specify buffers that should be
displayed specially. If the buffer's name matches any of the regular
expressions in this list, @code{display-buffer} handles the buffer
If an element is a list, instead of a string, then the @sc{car} of the
list is the regular expression, and the rest of the list says how to
create the frame. See above, under @code{special-display-buffer-names}.
-@end defvar
+@end defopt
@defvar special-display-function
This variable holds the function to call to display a buffer specially.
Emacs does not know the position of the end of display in that window.
In that case, this function returns @code{nil}.
-If you @var{update} is non-@code{nil}, @code{window-end} always returns
+If @var{update} is non-@code{nil}, @code{window-end} always returns
an up-to-date value for where the window ends. If the saved value is
valid, @code{window-end} returns that; otherwise it computes the correct
value by scanning the buffer text.
which buffer to scroll.
@end defvar
-@defopt scroll-step
+@tindex scroll-margin
+@defopt scroll-margin
+This option specifies the size of the scroll margin---a minimum number
+of lines between point and the top or bottom of a window. Whenever
+point gets within this many lines of the top or bottom of the window,
+the window scrolls automatically (if possible) to move point out of the
+margin, closer to the center of the window.
+@end defopt
+
+@tindex scroll-conservatively
+@defopt scroll-conservatively
This variable controls how scrolling is done automatically when point
-moves off the screen. If the value is zero, then redisplay scrolls the
-text to center point vertically in the window. If the value is a
-positive integer @var{n}, then redisplay brings point back on screen by
-scrolling @var{n} lines in either direction, if possible; otherwise, it
-centers point. The default value is zero.
+moves off the screen (or into the scroll margin). If the value is zero,
+then redisplay scrolls the text to center point vertically in the
+window. If the value is a positive integer @var{n}, then redisplay
+scrolls the window up to @var{n} lines in either direction, if that will
+bring point back into view. Otherwise, it centers point. The default
+value is zero.
+@end defopt
+
+@defopt scroll-step
+This variable is an older variant of @code{scroll-conservatively}. The
+difference is that it if its value is @var{n}, that permits scrolling
+only by precisely @var{n} lines, not a smaller number. This feature
+does not work with @code{scroll-margin}. The default value is zero.
+@end defopt
+
+@tindex scroll-preserve-screen-position
+@defopt scroll-preserve-screen-position
+If this option is non-@code{nil}, the scroll functions move point so
+that the vertical position of the cursor is unchanged, when that is
+possible.
@end defopt
@defopt next-screen-context-lines
@end example
@end deffn
+@deffn Command shrink-window-if-larger-than-buffer window
+This command shrinks @var{window} to be as small as possible while still
+showing the full contents of its buffer---but not less than
+@code{window-min-height} lines.
+
+However, the command does nothing if the window is already too small to
+display the whole text of the buffer, or if part of the contents are
+currently scrolled off screen, or if the window is not the full width of
+its frame, or if the window is the only window in its frame.
+@end deffn
+
@cindex minimum window size
The following two variables constrain the window-size-changing
functions to a minimum height and width.
@defopt window-min-width
The value of this variable determines how narrow a window may become
-before it automatically deleted. Making a window smaller than
+before it is automatically deleted. Making a window smaller than
@code{window-min-width} automatically deletes it, and no window may be
created narrower than this. The absolute minimum width is one; any
value below that is ignored. The default value is 10.
Displaying a different buffer in the window also runs these functions.
-These functions cannot expect @code{window-end} (@pxref{Window Start})
-to return a meaningful value, because that value is updated only by
-redisplaying the buffer. So if one of these functions needs to know the
-last character that will fit in the window with its current
-display-start position, it has to find that character using
-@code{vertical-motion} (@pxref{Screen Lines}).
+These functions must be careful in using @code{window-end}
+(@pxref{Window Start}); if you need an up-to-date value, you must use
+the @var{update} argument to ensure you get it.
@end defvar
@defvar window-size-change-functions
@defvar redisplay-end-trigger-functions
@tindex redisplay-end-trigger-functions
-This abnormal hook is run whenever redisplay in window uses text that
+This abnormal hook is run whenever redisplay in a 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
functions are called with two arguments: the window, and the end trigger
projects / emacs.git / commitdiff