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

*** empty log message ***

Browse source
This commit is contained in:
Richard M. Stallman 1998-05-26 18:56:56 +00:00
parent e197b151df
commit 1911e6e52c
33 changed files with 772 additions and 462 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

119
lispref/advice.texi
View file

@ -12,10 +12,12 @@ function, by @dfn{advising the function}. This is a clean method for a
library to customize functions defined by other parts of Emacs---cleaner
than redefining the 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
@ -25,12 +27,13 @@ function (or a new command) which uses the existing function.
@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
@ -63,7 +66,6 @@ this:
(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
@ -100,10 +102,12 @@ expression to wrap around the invocation of the base definition.
@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
@ -132,14 +136,13 @@ wrapped around the execution of the function itself. After-advice and
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
@ -152,11 +155,12 @@ definition calls for several different pieces of information.
The optional @var{position} specifies where, in the current list of
advice of the specified @var{class}, this new advice should be placed.
It should be either @code{first}, @code{last} or a number that
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
@ -168,12 +172,11 @@ This argument list must be compatible with the argument list of the
original function, so that it can handle the ways the function is
actually called. If more than one piece of advice specifies an argument
list, then the first one (the one with the smallest position) found in
the list of all classes of advice is used. Numbers outside the range
are mapped to the beginning or the end, whichever is closer.
the 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
@ -190,8 +193,8 @@ activate an undefined function's advice. However, defining
@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
@ -233,6 +236,38 @@ expanded when a program is compiled, not when a compiled program is run.
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
@ -270,6 +305,7 @@ replaced with the new one.
@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
@ -302,10 +338,13 @@ This command activates the advice for @var{function}.
To activate advice for a function whose advice is already active is not
a no-op. It is a useful operation which puts into effect any changes in
advice since the previous activation of that function's advice.
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
@ -323,7 +362,7 @@ which has at least one piece of advice that matches @var{regexp}.
@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}.
@ -332,6 +371,7 @@ function which has at least one piece of advice that matches
@deffn Command ad-update-regexp regexp &optional compile
This command activates pieces of advice whose names match @var{regexp},
but only those 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
@ -355,17 +395,20 @@ This variable controls whether to compile the combined definition
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}:
@ -373,7 +416,7 @@ 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:
@ -408,6 +451,8 @@ This command enables all pieces of advice whose names match
@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
@ -486,7 +531,7 @@ for that function.
A more robust method is to use macros that are translated into the
proper access forms at activation time, i.e., when constructing the
advised definition. Access macros access actual arguments by position
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.

2
lispref/anti.texi
View file

@ -73,7 +73,7 @@ or the strings are not equal.
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

22
lispref/backups.texi
View file

@ -588,17 +588,17 @@ about them, you can get rid of them by reading in the previous version
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},
@ -616,6 +616,14 @@ buffer. Preserving any additional markers would be problematical.
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

29
lispref/buffers.texi
View file

@ -213,7 +213,7 @@ If the buffer that used to be current has been killed by the time of
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
@ -427,7 +427,7 @@ the same file name. In such cases, this function returns the first
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}
@ -440,6 +440,13 @@ If @var{filename} is @code{nil} or the empty string, that stands for
``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.
@ -723,21 +730,21 @@ live buffer.
@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

4
lispref/calendar.texi
View file

@ -577,7 +577,7 @@ HHeshvan 25 Happy Hebrew birthday!
@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
@ -668,7 +668,7 @@ shown in the fancy diary buffer, set the variable
@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

10
lispref/commands.texi
View file

@ -1589,7 +1589,7 @@ buffer position. Here's how to do that:
(- (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
@ -1652,7 +1652,8 @@ and such numbers cannot be included in a string.
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
@ -1854,7 +1855,7 @@ If @code{cursor-in-echo-area} is non-@code{nil}, then @code{read-event}
moves the cursor temporarily to the echo area, to the end of any message
displayed there. Otherwise @code{read-event} does not move the cursor.
If @code{read-event} gets an event is defined as a help character, in
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
@ -1948,7 +1949,8 @@ What character-@kbd{177}
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

6
lispref/customize.texi
View file

@ -372,9 +372,9 @@ The value must be a directory name, and you can do completion with
@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

8
lispref/debugging.texi
View file

@ -124,7 +124,7 @@ the debugger gets a chance.
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
@ -139,9 +139,9 @@ enter the debugger.
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
@ -737,7 +737,7 @@ the old indentation actually fit the intended nesting of parentheses,
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

128
lispref/display.texi
View file

@ -11,7 +11,6 @@ that Emacs presents to the user.
@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.
@ -33,7 +32,7 @@ that Emacs presents to the user.
@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
@ -65,65 +64,6 @@ has been suspended and resumed. Non-@code{nil} means there is no need
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
@ -173,7 +113,7 @@ a window, that forces truncation.
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
@ -395,7 +335,7 @@ overlaps the overlay on exit from the search.
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
@ -1093,7 +1033,7 @@ subsequent elements of @var{spec} are never used. Normally
@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
@ -1110,7 +1050,7 @@ What kinds of colors the frame supports---either @code{color},
@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
@ -1139,6 +1079,15 @@ with @code{defface}:
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
@ -1339,6 +1288,12 @@ for more information about Transient Mark mode.
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
@ -1356,23 +1311,23 @@ The value of @code{blink-paren-function} may be @code{nil}, in which
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
@ -1398,7 +1353,7 @@ Here is an example of calling this function explicitly.
(blink-matching-open)))
@end group
@end smallexample
@end defun
@end deffn
@node Inverse Video
@section Inverse Video
@ -1655,13 +1610,13 @@ below).
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.
@ -1705,13 +1660,13 @@ It also terminates any keyboard macro currently executing unless
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
@ -1728,11 +1683,20 @@ differently. An Emacs frame is a single window as far as X is
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

57
lispref/edebug.texi
View file

@ -9,7 +9,7 @@
@c , Bugs and Todo List, Top, Top
@node Edebug,, Compilation Errors, Debugging
@node Edebug, Syntax Errors, Debugger, Debugging
@section Edebug
@cindex Edebug mode
@ -583,10 +583,12 @@ position (@code{edebug-bounce-point}). With a prefix argument @var{n},
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
@ -842,11 +844,10 @@ with @code{(apply 'format @var{format-string} @var{format-args})}.
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
@ -855,18 +856,22 @@ last lines inserted.
@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.
frequency.
Use @kbd{M-x edebug-display-freq-count} to display both the
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
@ -882,7 +887,7 @@ count of an earlier expression on the same line.
The character @samp{=} following the count for an expression says that
the expression has returned the same value each time it was evaluated.
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}.
@ -1073,7 +1078,7 @@ name.
@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
@ -1143,7 +1148,7 @@ their meanings:
@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
@ -1180,8 +1185,8 @@ elements must all match or none, use @code{&optional
@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

19
lispref/elisp.texi
View file

@ -66,11 +66,10 @@ instead of in the original English.
@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
@ -81,9 +80,9 @@ Copyright @copyright{} 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1998 Free Softw
@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 @*
@ -271,7 +270,7 @@ Editing Types
* Process Type:: A process running on the underlying OS.
* Stream Type:: Receive or send characters.
* Keymap Type:: What function a keystroke invokes.
* Overlay Type:: How an overlay is represented.
* Overlay Type:: How an overlay is represented.
Numbers
@ -292,7 +291,7 @@ Strings and Characters
* 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
@ -454,7 +453,7 @@ Advising Functions
* 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.
@ -692,14 +691,14 @@ Frames
* 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.

2
lispref/errors.texi
View file

@ -55,7 +55,7 @@ See @code{/} and @code{%} in @ref{Numbers}.
@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

134
lispref/frames.texi
View file

@ -50,12 +50,15 @@ This predicate returns @code{t} if @var{object} is a frame, and
* 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
@ -92,11 +95,10 @@ frame just created.
@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
@ -104,16 +106,18 @@ another display, use the command @code{make-frame-on-display} or specify
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
@ -164,8 +168,8 @@ Just what parameters a frame has depends on what display mechanism it
uses.
Frame parameters exist for the sake of window systems. A terminal frame
has a few parameters, 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
@ -418,9 +422,20 @@ appears. If this is @code{nil}, the frame's title is used.
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.
@ -430,6 +445,11 @@ The color for the cursor that shows point.
@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}
@ -470,6 +490,10 @@ it and see if it works.)
@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
@ -481,15 +505,28 @@ by the window manager in its usual fashion.
@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
@ -515,15 +552,38 @@ To set the size based on values measured in pixels, use
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}.
@ -562,17 +622,11 @@ Here is an example:
@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
@ -768,8 +822,7 @@ actually displayed on the terminal. @code{switch-frame} is the only way
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
@ -1283,7 +1336,7 @@ just as fonts do, and you can use a fontset name in place of a font name
when you specify the ``font'' for a frame or a face. Here is
information about defining a fontset under Lisp program control.
@defun create-fontset-from-fontset-spec fontset-spec &optional style noerror
@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:
@ -1298,22 +1351,23 @@ The first part of the string, @var{fontpattern}, should have the form of
a standard X font name, except that the last two fields should be
@samp{fontset-@var{alias}}.
Each fontset has two names, one long and one short. The long name is
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
@ -1354,7 +1408,7 @@ and the font specification for Chinese GB2312 characters would be this:
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
@ -1415,7 +1469,7 @@ defined, the value is @code{nil}.
@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

12
lispref/help.texi
View file

@ -99,15 +99,15 @@ Help, emacs, The GNU Emacs Manual}.
@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}.)
@ -116,7 +116,7 @@ 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)
@ -218,7 +218,7 @@ goal-column Option
@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!
@ -496,7 +496,7 @@ stands for @kbd{C-h}. When Emacs reads this character, if
@code{help-form} is a non-@code{nil} Lisp expression, it evaluates that
expression, and displays the result in a window if it is a string.
Usually the value of @code{help-form}'s value is @code{nil}. Then the
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

4
lispref/intro.texi
View file

@ -491,10 +491,6 @@ mail @emph{will} be acted on in due time. If you want to contact the
Emacs maintainers more quickly, send mail to
@code{bug-gnu-emacs@@gnu.org}.
@display
--Bil Lewis, Dan LaLiberte, Richard Stallman
@end display
@node Lisp History
@section Lisp History
@cindex Lisp history

57
lispref/keymaps.texi
View file

@ -338,7 +338,8 @@ For example, @kbd{C-x} is a prefix key, and it uses a keymap that is
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
@ -369,6 +370,12 @@ mode-specific bindings.
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
@ -384,11 +391,28 @@ key.
@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
@ -615,7 +639,7 @@ particular minor modes. The elements of this alist look like the
elements of @code{minor-mode-map-alist}: @code{(@var{variable}
. @var{keymap})}.
If a variable appears an element 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}.
@ -1179,16 +1203,15 @@ Dired mode is set up:
@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

8
lispref/loading.texi
View file

@ -148,7 +148,8 @@ Normally, the variable's value is @code{nil}, which means those
functions should use @code{read}.
@end defvar
For how @code{load} is used to build Emacs, see @ref{Building Emacs}.
For information about how @code{load} is used in building Emacs, see
@ref{Building Emacs}.
@node Library Search
@section Library Search
@ -176,16 +177,15 @@ directory names, and @samp{.} is used for the current default directory.
Here is an example of how to set your @code{EMACSLOADPATH} variable from
a @code{csh} @file{.login} file:
@c This overfull hbox is OK. --rjc 16mar92
@smallexample
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

6
lispref/markers.texi
View file

@ -316,9 +316,9 @@ relocating a marker to point after the inserted text.
@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

23
lispref/minibuf.texi
View file

@ -38,7 +38,7 @@ minibuffer. However, many operations for managing buffers do not apply
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}.)
@ -136,10 +136,10 @@ properties were present in the minibuffer. Otherwise all the text
properties are stripped when the value is returned.
If the argument @var{inherit-input-method} is non-@code{nil}, then the
minibuffer inherits the current 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
@ -191,10 +191,13 @@ This function is a simplified interface to 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
@ -679,7 +682,7 @@ edit the input, providing several commands to attempt completion.
In most cases, we recommend using @var{default}, and not @var{initial}.
If the argument @var{inherit-input-method} is non-@code{nil}, then the
minibuffer inherits the current 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.
@ -1003,7 +1006,7 @@ predicate @code{user-variable-p} instead of @code{commandp}:
@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
@ -1035,7 +1038,7 @@ initial input. It defaults to the current buffer's value of
@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

37
lispref/modes.texi
View file

@ -60,7 +60,7 @@ definition is distinct from that of Text mode, but was derived from it.
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
@ -823,11 +823,11 @@ minor modes.
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
@ -887,6 +887,9 @@ check for an existing element, to avoid duplication. For example:
@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
@ -1135,6 +1138,11 @@ directory.
@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
@ -1174,12 +1182,8 @@ frame at a time.
@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
@ -1240,7 +1244,7 @@ This buffer-local variable contains the mode line information on process
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
@ -1456,8 +1460,8 @@ Setting this variable makes it buffer-local in the current buffer.
@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})
@ -1478,7 +1482,7 @@ For example, Fortran mode uses it this way:
@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
@ -2081,7 +2085,9 @@ each of them the arguments @var{args}.
This function is the way to run an abnormal hook which passes arguments
to the hook functions, and stops as soon as any hook function fails. It
calls each of the hook functions, passing each of them the arguments
@var{args}, until some hook function returns @code{nil}. Then it stops.
@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
@ -2089,7 +2095,8 @@ This function is the way to run an abnormal hook which passes arguments
to the hook functions, and stops as soon as any hook function succeeds.
It calls each of the hook functions, passing each of them the arguments
@var{args}, until some hook function returns non-@code{nil}. Then it
stops.
stops, and returns whatever was returned by the last hook function
that was called.
@end defun
@defun add-hook hook function &optional append local

83
lispref/nonascii.texi
View file

@ -46,13 +46,14 @@ character set by setting the variable @code{nonascii-insert-offset}).
@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.
@ -156,14 +157,14 @@ If this is non-@code{nil}, it overrides @code{nonascii-insert-offset}.
@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
@ -280,18 +281,18 @@ set that @var{character} belongs to.
@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
@ -481,6 +482,7 @@ by a particular @dfn{coding system}.
* Coding System Basics::
* Encoding and I/O::
* Lisp and Coding Systems::
* User-Chosen Coding Systems::
* Default Coding Systems::
* Specifying Coding Systems::
* Explicit Encoding::
@ -559,7 +561,7 @@ as an alias for the coding system.
@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.
@ -632,7 +634,7 @@ Otherwise it signals an error with condition @code{coding-system-error}.
@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.
@ -692,6 +694,31 @@ is @code{undecided} or @code{(undecided)}.
@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
@ -713,15 +740,12 @@ the user tries to enter null input, it asks the user to try again.
@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
@ -738,7 +762,7 @@ reading and writing particular files. Each element has the form
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
@ -763,7 +787,7 @@ other coding systems later using @code{set-process-coding-system}.
@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
@ -917,6 +941,15 @@ write them with @code{write-region} (@pxref{Writing to Files}), and
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
@ -1092,12 +1125,14 @@ This variable defines all the supported input methods.
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
@ -1107,6 +1142,6 @@ it is good for.
@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

50
lispref/os.texi
View file

@ -19,6 +19,7 @@ pertaining to the terminal and the screen.
* 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).
@ -195,6 +196,7 @@ loading of this file with the option @samp{-no-site-file}.
@defvar site-run-file
This variable specifies the site-customization file to load
before the user's init file. Its normal value is @code{"site-start"}.
(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
@ -214,12 +216,13 @@ then the default library is not loaded. The default value is
@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
@ -568,6 +571,9 @@ The value of this variable is a symbol indicating the type of operating
system Emacs is operating on. Here is a table of the possible values:
@table @code
@item alpha-vms
VMS on the Alpha.
@item aix-v3
AIX.
@ -727,13 +733,13 @@ containing the Emacs executable.
@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
@ -864,6 +870,29 @@ This function returns the real @sc{uid} of the user.
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
@ -1129,7 +1158,7 @@ after a certain length of idleness.
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.
@ -1139,8 +1168,9 @@ at time @var{time}. The argument @var{function} is a function to call
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}
@ -1664,7 +1694,7 @@ It is not crucial to exclude from the alist the keysyms of other X
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
@ -1684,7 +1714,7 @@ entries and DEC terminal concentrators, see @file{emacs/etc/TERMS}.
@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

21
lispref/positions.texi
View file

@ -180,13 +180,15 @@ whether a given character is part of a word. @xref{Syntax Tables}.
@deffn Command forward-word count
This function moves point forward @var{count} words (or backward if
@var{count} is negative). 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.
@ -657,7 +659,7 @@ This function moves point in the current buffer forward, skipping over a
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
@ -699,6 +701,9 @@ comes back" twice.
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
@ -765,7 +770,7 @@ The value returned by @code{save-excursion} is the result of the last of
@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

43
lispref/processes.texi
View file

@ -79,12 +79,12 @@ Expansion}).
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}
@ -102,14 +102,14 @@ must use @var{args} to provide those.
@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
@ -224,7 +224,7 @@ parallel with Emacs; but you can think of it as synchronous in that
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}.
@ -365,8 +365,8 @@ then returns the command's output as a string.
@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
@ -484,13 +484,13 @@ deleted automatically after they terminate, but not necessarily right
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
@ -505,10 +505,15 @@ the name of a process, a buffer, or the name of a buffer.
@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
@ -1145,9 +1150,7 @@ subprocess output.
The argument @var{seconds} need not be an integer. If it is a floating
point number, this function waits for a fractional number of seconds.
Some systems support only a whole number of seconds; on these systems,
@var{seconds} is rounded down. If the system doesn't support waiting
fractions of a second, you get an error if you specify nonzero
@var{millisec}.
@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

14
lispref/searching.texi
View file

@ -234,7 +234,7 @@ backtracking loops. For example, it could take hours for the regular
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.
@ -266,9 +266,9 @@ matches @samp{cr}, @samp{car}, @samp{cdr}, @samp{caddaar}, etc.
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
@ -280,9 +280,9 @@ does match all non-@sc{ASCII} characters, in both multibyte and unibyte
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
@ -1286,7 +1286,7 @@ that shows the problem that arises if you fail to save the match data:
You can save and restore the match data with @code{save-match-data}:
@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

14
lispref/sequences.texi
View file

@ -637,7 +637,7 @@ name. @xref{Splitting Characters}, for a description of generic characters.
@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
@ -678,11 +678,13 @@ The return value is always @code{nil}; to make this function useful,
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)))

23
lispref/streams.texi
View file

@ -389,11 +389,6 @@ initially located as shown immediately before the @samp{h} in
@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.
@ -403,10 +398,6 @@ 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
@ -431,8 +422,8 @@ This is the @point{}output
@end group
@group
m
@result{} #<marker at 11 in foo>
(setq m (copy-marker 10))
@result{} #<marker at 10 in foo>
@end group
@group
@ -450,7 +441,7 @@ he @point{}output
@group
m
@result{} #<marker at 35 in foo>
@result{} #<marker at 34 in foo>
@end group
@end example
@ -723,6 +714,14 @@ In the second expression, the local binding of
@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

6
lispref/strings.texi
View file

@ -439,9 +439,9 @@ the string). The specified part of @var{string2} runs from index
@var{start2} up to index @var{end2} (default, the end of the string).
The strings are both converted to multibyte for the comparison
(@pxref{Text Representations}) so that a unibyte string can be usefully
compared with a multibyte string. If @var{ignore-case} is
non-@code{nil}, then case is ignored as well.
(@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

11
lispref/syntax.texi
View file

@ -362,7 +362,7 @@ character, @samp{/}, does have the @samp{b} flag.
@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
@ -542,10 +542,8 @@ This function moves point forward across characters having syntax classes
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
@ -553,10 +551,9 @@ This function moves point backward across characters whose syntax
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
@ -598,7 +595,7 @@ stops when it comes to any character that starts a sexp. If
@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
@ -893,7 +890,7 @@ in category table @var{table}.
@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

144
lispref/text.texi
View file

@ -42,6 +42,7 @@ buffer, together with their properties (when relevant).
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.
@ -62,11 +63,12 @@ buffer, together with their properties (when relevant).
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{@@}:
@ -79,11 +81,12 @@ 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
@ -449,9 +452,12 @@ Programs hardly ever use this function.
@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
@ -467,7 +473,7 @@ cases.
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
@ -478,7 +484,7 @@ auto-saving of that buffer ``because it has shrunk''. However,
@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
@ -779,6 +785,12 @@ is convenient because it lets the user use all the kill commands to copy
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
@ -1000,10 +1012,11 @@ A value of @code{t} disables the recording of undo information.
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.
@ -1037,11 +1050,6 @@ relocated due to deletion of surrounding text, and that it moved
@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
@ -1185,11 +1193,16 @@ It uses the ordinary paragraph motion commands to find paragraph
boundaries. @xref{Paragraphs,,, emacs, The Emacs Manual}.
@end deffn
@deffn Command fill-region start end &optional justify
@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
@ -1220,7 +1233,7 @@ This variable alters the action of @code{fill-individual-paragraphs} as
described above.
@end defopt
@deffn Command fill-region-as-paragraph start end &optional justify
@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
@ -1228,11 +1241,13 @@ filling when @var{justify} is non-@code{nil}.
In an interactive call, any prefix argument requests justification.
@cindex Adaptive Fill mode
In Adaptive Fill mode, which is enabled by default, calling the function
@code{fill-region-as-paragraph} on an indented paragraph when there is
no fill prefix uses the indentation of the second line of the paragraph
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
@ -1267,6 +1282,12 @@ This function returns the proper justification style to use for filling
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
@ -1306,7 +1327,7 @@ together. The resulting filled lines also start with the fill prefix.
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
@ -1316,7 +1337,7 @@ As a practical matter, if you are writing text for other people to
read, you should set @code{fill-column} to no more than 70. Otherwise
the line will be too long for people to read comfortably, and this can
make the text seem clumsy.
@end defvar
@end defopt
@defvar default-fill-column
The value of this variable is the default value for @code{fill-column} in
@ -1392,6 +1413,50 @@ place where a break is being considered. If the function returns
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
@ -1513,10 +1578,11 @@ the sort order.
@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
@ -1531,8 +1597,11 @@ its @code{sort-subr} call looks like this:
@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
@ -1541,6 +1610,11 @@ Markers pointing into any sort records are left with no useful
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}.
@ -1823,7 +1897,7 @@ but in some text modes, where @key{TAB} inserts a tab,
@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
@ -3177,7 +3251,7 @@ end of the region just changed, and the length of the text that existed
before the change. All three arguments are integers. The buffer that's
about to change is always the current buffer.
The length of the old text 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.

8
lispref/tips.texi
View file

@ -354,7 +354,7 @@ compiled specially (@pxref{Array Functions}):
@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
@ -396,7 +396,7 @@ that looks good.
@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
@ -478,8 +478,8 @@ t and nil without single-quotes. (In this manual, we use a different
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

2
lispref/variables.texi
View file

@ -1073,7 +1073,7 @@ and/or frames is an important customization method.
This section describes buffer-local bindings; for frame-local
bindings, see the following section, @ref{Frame-Local Variables}. (A few
variables have bindings that are local to each X terminal; see
variables have bindings that are local to each terminal; see
@ref{Multiple Displays}.)
@menu

128
lispref/windows.texi
View file

@ -252,10 +252,13 @@ characters; see @ref{Display Tables}.
@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
@ -272,7 +275,7 @@ Here is the complete function definition for it:
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):
@ -366,16 +369,20 @@ where there is only one window), then the frame reverts to having a
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.
@ -463,8 +470,8 @@ If there are two windows of the same size, then the function returns
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
@ -677,7 +684,7 @@ This variable records the time at which a buffer was last made visible
in a window. It is always local in each buffer; each time
@code{set-window-buffer} is called, it sets this variable to
@code{(current-time)} in the specified buffer (@pxref{Time of Day}).
When a buffer is first created, @code{buffer-display-count} starts out
When a buffer is first created, @code{buffer-display-time} starts out
with the value @code{nil}.
@end defvar
@ -704,9 +711,9 @@ functions work by calling @code{set-window-buffer}.
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
@ -824,11 +831,23 @@ function does nothing.
@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.
@ -882,7 +901,7 @@ This variable holds an alist specifying frame parameters used when
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.
@ -895,9 +914,9 @@ frame. There are two possibilities for the rest of the list. It can be
an alist, specifying frame parameters, or it can contain a function and
arguments to give to it. (The function's first argument is always the
buffer to be displayed; the arguments from the list come after that.)
@end defvar
@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
@ -908,7 +927,7 @@ By default, special display means to give the buffer a dedicated frame.
If an element is a list, instead of a string, then the @sc{car} of the
list is the regular expression, and the rest of the list says how to
create the frame. See above, under @code{special-display-buffer-names}.
@end defvar
@end defopt
@defvar special-display-function
This variable holds the function to call to display a buffer specially.
@ -1084,7 +1103,7 @@ If the last redisplay of @var{window} was preempted, and did not finish,
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.
@ -1253,13 +1272,38 @@ If this variable is non-@code{nil}, it tells @code{scroll-other-window}
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
@ -1608,6 +1652,17 @@ It could be defined as follows:
@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.
@ -1624,7 +1679,7 @@ less than two. The default value is 4.
@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.
@ -1813,12 +1868,9 @@ display-start position.
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
@ -1846,7 +1898,7 @@ Windows}) is what you need here.
@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