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:
Karl Heuer 1995-06-05 12:23:13 +00:00
parent a8a818c00e
commit 22697dac66
27 changed files with 1905 additions and 457 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

295
lispref/buffers.texi
View file

@ -17,6 +17,8 @@ not be displayed in any windows.
@menu
* Buffer Basics:: What is a buffer?
* Current Buffer:: Designating a buffer as current
so primitives will access its contents.
* Buffer Names:: Accessing and changing buffer names.
* Buffer File Name:: The buffer file name indicates which file is visited.
* Buffer Modification:: A buffer is @dfn{modified} if it needs to be saved.
@ -26,8 +28,7 @@ not be displayed in any windows.
* The Buffer List:: How to look at all the existing buffers.
* Creating Buffers:: Functions that create buffers.
* Killing Buffers:: Buffers exist until explicitly killed.
* Current Buffer:: Designating a buffer as current
so primitives will access its contents.
* Indirect Buffers:: An indirect buffer shares text with some other buffer.
@end menu
@node Buffer Basics
@ -75,6 +76,130 @@ This function returns @code{t} if @var{object} is a buffer,
@code{nil} otherwise.
@end defun
@node Current Buffer
@section The Current Buffer
@cindex selecting a buffer
@cindex changing to another buffer
@cindex current buffer
There are, in general, many buffers in an Emacs session. At any time,
one of them is designated as the @dfn{current buffer}. This is the
buffer in which most editing takes place, because most of the primitives
for examining or changing text in a buffer operate implicitly on the
current buffer (@pxref{Text}). Normally the buffer that is displayed on
the screen in the selected window is the current buffer, but this is not
always so: a Lisp program can designate any buffer as current
temporarily in order to operate on its contents, without changing what
is displayed on the screen.
The way to designate a current buffer in a Lisp program is by calling
@code{set-buffer}. The specified buffer remains current until a new one
is designated.
When an editing command returns to the editor command loop, the
command loop designates the buffer displayed in the selected window as
current, to prevent confusion: the buffer that the cursor is in when
Emacs reads a command is the buffer that the command will apply to.
(@xref{Command Loop}.) Therefore, @code{set-buffer} is not the way to
switch visibly to a different buffer so that the user can edit it. For
this, you must use the functions described in @ref{Displaying Buffers}.
However, Lisp functions that change to a different current buffer
should not depend on the command loop to set it back afterwards.
Editing commands written in Emacs Lisp can be called from other programs
as well as from the command loop. It is convenient for the caller if
the subroutine does not change which buffer is current (unless, of
course, that is the subroutine's purpose). Therefore, you should
normally use @code{set-buffer} within a @code{save-excursion} that will
restore the current buffer when your function is done
(@pxref{Excursions}). Here is an example, the code for the command
@code{append-to-buffer} (with the documentation string abridged):
@example
@group
(defun append-to-buffer (buffer start end)
"Append to specified buffer the text of the region.
@dots{}"
(interactive "BAppend to buffer: \nr")
(let ((oldbuf (current-buffer)))
(save-excursion
(set-buffer (get-buffer-create buffer))
(insert-buffer-substring oldbuf start end))))
@end group
@end example
@noindent
This function binds a local variable to the current buffer, and then
@code{save-excursion} records the values of point, the mark, and the
original buffer. Next, @code{set-buffer} makes another buffer current.
Finally, @code{insert-buffer-substring} copies the string from the
original current buffer to the new current buffer.
If the buffer appended to happens to be displayed in some window,
the next redisplay will show how its text has changed. Otherwise, you
will not see the change immediately on the screen. The buffer becomes
current temporarily during the execution of the command, but this does
not cause it to be displayed.
If you make local bindings (with @code{let} or function arguments) for
a variable that may also have buffer-local bindings, make sure that the
same buffer is current at the beginning and at the end of the local
binding's scope. Otherwise you might bind it in one buffer and unbind
it in another! There are two ways to do this. In simple cases, you may
see that nothing ever changes the current buffer within the scope of the
binding. Otherwise, use @code{save-excursion} to make sure that the
buffer current at the beginning is current again whenever the variable
is unbound.
It is not reliable to change the current buffer back with
@code{set-buffer}, because that won't do the job if a quit happens while
the wrong buffer is current. Here is what @emph{not} to do:
@example
@group
(let (buffer-read-only
(obuf (current-buffer)))
(set-buffer @dots{})
@dots{}
(set-buffer obuf))
@end group
@end example
@noindent
Using @code{save-excursion}, as shown below, handles quitting, errors,
and @code{throw}, as well as ordinary evaluation.
@example
@group
(let (buffer-read-only)
(save-excursion
(set-buffer @dots{})
@dots{}))
@end group
@end example
@defun current-buffer
This function returns the current buffer.
@example
@group
(current-buffer)
@result{} #<buffer buffers.texi>
@end group
@end example
@end defun
@defun set-buffer buffer-or-name
This function makes @var{buffer-or-name} the current buffer. It does
not display the buffer in the currently selected window or in any other
window, so the user cannot necessarily see the buffer. But Lisp
programs can in any case work on it.
This function returns the buffer identified by @var{buffer-or-name}.
An error is signaled if @var{buffer-or-name} does not identify an
existing buffer.
@end defun
@node Buffer Names
@section Buffer Names
@cindex buffer names
@ -533,6 +658,12 @@ If @var{buffer-or-name} is not supplied (or if it is not a buffer),
then @code{other-buffer} returns the first buffer on the buffer list
that is not 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{X Frame
Parameters}.
@c Emacs 19 feature
If @var{visible-ok} is @code{nil}, @code{other-buffer} avoids returning
a buffer visible in any window on any visible frame, except as a last
@ -589,8 +720,9 @@ An error is signaled if @var{name} is not a string.
@end group
@end example
The major mode for the new buffer is set according to the variable
@code{default-major-mode}. @xref{Auto Major Mode}.
The major mode for the new buffer is set to Fundamental mode. The
variable @code{default-major-mode} is handled at a higher level.
@xref{Auto Major Mode}.
@end defun
@defun generate-new-buffer name
@ -618,8 +750,9 @@ An error is signaled if @var{name} is not a string.
@end group
@end example
The major mode for the new buffer is set by the value of
@code{default-major-mode}. @xref{Auto Major Mode}.
The major mode for the new buffer is set to Fundamental mode. The
variable @code{default-major-mode} is handled at a higher level.
@xref{Auto Major Mode}.
See the related function @code{generate-new-buffer-name} in @ref{Buffer
Names}.
@ -713,126 +846,48 @@ variable @code{buffer-offer-save} automatically becomes buffer-local
when set for any reason. @xref{Buffer-Local Variables}.
@end defvar
@node Current Buffer
@section The Current Buffer
@cindex selecting a buffer
@cindex changing to another buffer
@cindex current buffer
@node Indirect Buffers
@section Indirect Buffers
@cindex indirect buffers
@cindex base buffer
There are, in general, many buffers in an Emacs session. At any time,
one of them is designated as the @dfn{current buffer}. This is the
buffer in which most editing takes place, because most of the primitives
for examining or changing text in a buffer operate implicitly on the
current buffer (@pxref{Text}). Normally the buffer that is displayed on
the screen in the selected window is the current buffer, but this is not
always so: a Lisp program can designate any buffer as current
temporarily in order to operate on its contents, without changing what
is displayed on the screen.
An @dfn{indirect buffer} shares the text of some other buffer, which
is called the @dfn{base buffer} of the indirect buffer. In some ways it
is the equivalent, for buffers, of a symbolic link among files. The base
buffer may not itself be an indirect buffer.
The way to designate a current buffer in a Lisp program is by calling
@code{set-buffer}. The specified buffer remains current until a new one
is designated.
The text of the indirect buffer is always identical to the text of its
base buffer; changes made by editing either one are visible immediately
in the other. This includes the text properties as well as the characters
themselves.
When an editing command returns to the editor command loop, the
command loop designates the buffer displayed in the selected window as
current, to prevent confusion: the buffer that the cursor is in when
Emacs reads a command is the buffer that the command will apply to.
(@xref{Command Loop}.) Therefore, @code{set-buffer} is not the way to
switch visibly to a different buffer so that the user can edit it. For
this, you must use the functions described in @ref{Displaying Buffers}.
But in all other respects, the indirect buffer and its base buffer are
completely separate. They have different names, different values of
point, different narrowing, different markers and overlays (though
inserting or deleting text in either buffer relocates the markers and
overlays for both), different major modes, and different local
variables.
However, Lisp functions that change to a different current buffer
should not depend on the command loop to set it back afterwards.
Editing commands written in Emacs Lisp can be called from other programs
as well as from the command loop. It is convenient for the caller if
the subroutine does not change which buffer is current (unless, of
course, that is the subroutine's purpose). Therefore, you should
normally use @code{set-buffer} within a @code{save-excursion} that will
restore the current buffer when your function is done
(@pxref{Excursions}). Here is an example, the code for the command
@code{append-to-buffer} (with the documentation string abridged):
An indirect buffer cannot visit a file, but its base buffer can. If
you try to save the indirect buffer, that actually works by saving the
base buffer.
@example
@group
(defun append-to-buffer (buffer start end)
"Append to specified buffer the text of the region.
@dots{}"
(interactive "BAppend to buffer: \nr")
(let ((oldbuf (current-buffer)))
(save-excursion
(set-buffer (get-buffer-create buffer))
(insert-buffer-substring oldbuf start end))))
@end group
@end example
Killing an indirect buffer has no effect on its base buffer. Killing
the base buffer effectively kills the indirect buffer in that it cannot
ever again be the current buffer.
@noindent
This function binds a local variable to the current buffer, and then
@code{save-excursion} records the values of point, the mark, and the
original buffer. Next, @code{set-buffer} makes another buffer current.
Finally, @code{insert-buffer-substring} copies the string from the
original current buffer to the new current buffer.
@deffn Command make-indirect-buffer base-buffer name
This creates an indirect buffer named @var{name} whose base buffer
is @var{base-buffer}. The argument @var{base-buffer} may be a buffer
or a string.
If @var{base-buffer} is an indirect buffer, its base buffer is used as
the base for the new buffer.
@end deffn
If the buffer appended to happens to be displayed in some window,
the next redisplay will show how its text has changed. Otherwise, you
will not see the change immediately on the screen. The buffer becomes
current temporarily during the execution of the command, but this does
not cause it to be displayed.
If you make local bindings (with @code{let} or function arguments) for
a variable that may also have buffer-local bindings, make sure that the
same buffer is current at the beginning and at the end of the local
binding's scope. Otherwise you might bind it in one buffer and unbind
it in another! There are two ways to do this. In simple cases, you may
see that nothing ever changes the current buffer within the scope of the
binding. Otherwise, use @code{save-excursion} to make sure that the
buffer current at the beginning is current again whenever the variable
is unbound.
It is not reliable to change the current buffer back with
@code{set-buffer}, because that won't do the job if a quit happens while
the wrong buffer is current. Here is what @emph{not} to do:
@example
@group
(let (buffer-read-only
(obuf (current-buffer)))
(set-buffer @dots{})
@dots{}
(set-buffer obuf))
@end group
@end example
@noindent
Using @code{save-excursion}, as shown below, handles quitting, errors,
and @code{throw}, as well as ordinary evaluation.
@example
@group
(let (buffer-read-only)
(save-excursion
(set-buffer @dots{})
@dots{}))
@end group
@end example
@defun current-buffer
This function returns the current buffer.
@example
@group
(current-buffer)
@result{} #<buffer buffers.texi>
@end group
@end example
@defun buffer-base-buffer buffer
This function returns the base buffer of @var{buffer}. If @var{buffer}
is not indirect, the value is @code{nil}. Otherwise, the value is
another buffer, which is never an indirect buffer.
@end defun
@defun set-buffer buffer-or-name
This function makes @var{buffer-or-name} the current buffer. It does
not display the buffer in the currently selected window or in any other
window, so the user cannot necessarily see the buffer. But Lisp
programs can in any case work on it.
This function returns the buffer identified by @var{buffer-or-name}.
An error is signaled if @var{buffer-or-name} does not identify an
existing buffer.
@end defun

10
lispref/calendar.texi
View file

@ -66,7 +66,10 @@ asterisk (@samp{*}).
date as being a holiday. Its value may be a character to insert next to
the date, or a face name to use for displaying the date. Likewise, the
variable @code{diary-entry-marker} specifies how to mark a date that has
diary entries.
diary entries. The calendar creates faces named @code{holiday-face} and
@code{diary-face} for these purposes; those symbols are the default
values of these variables, when Emacs supports multiple faces on your
terminal.
@vindex calendar-load-hook
The variable @code{calendar-load-hook} is a normal hook run when the
@ -104,7 +107,10 @@ changing its face or by adding an asterisk. Here's how to use it:
@vindex calendar-today-marker
The variable @code{calendar-today-marker} specifies how to mark today's
date. Its value should be a character to insert next to the date or a
face name to use for displaying the date.
face name to use for displaying the date. A face named
@code{calendar-today-face} is provided for this purpose; that symbol is
the default for this variable when Emacs supports multiple faces on your
terminal.
@vindex today-invisible-calendar-hook
@noindent

44
lispref/commands.texi
View file

@ -370,6 +370,12 @@ The cursor does not move into the echo area. Prompt.
This kind of input is used by commands such as @code{describe-key} and
@code{global-set-key}.
@item K
A key sequence, whose definition you intend to change. This works like
@samp{k}, except that it suppresses, for the last input event in the key
sequence, the conversions that are normally used (when necessary) to
convert an undefined key into a defined one.
@item m
@cindex marker argument
The position of the mark, as an integer. No I/O.
@ -766,6 +772,7 @@ This function returns non-@code{nil} if @var{event} is an input event.
* Repeat Events:: Double and triple click (or drag, or down).
* Motion Events:: Just moving the mouse, not pushing a button.
* Focus Events:: Moving the mouse between frames.
* Misc Events:: Other events window systems can generate.
* Event Examples:: Examples of the lists for mouse events.
* Classifying Events:: Finding the modifier keys in an event symbol.
Event types.
@ -1223,6 +1230,34 @@ sequence---that is, after a prefix key---then Emacs reorders the events
so that the focus event comes either before or after the multi-event key
sequence, and not within it.
@node Misc Events
@subsection Miscellaneous Window System Events
A few other event types represent occurrences within the window system.
@table @code
@cindex @code{delete-frame} event
@item (delete-frame (@var{frame}))
This kind of event indicates that the user gave the window manager
a command to delete a particular window, which happens to be an Emacs frame.
The standard definition of the @code{delete-frame} event is to delete @var{frame}.
@cindex @code{iconify-frame} event
@item (iconify-frame (@var{frame}))
This kind of event indicates that the user iconified @var{frame} using
the window manager. Its standard definition is @code{ignore}; since
the frame has already been iconified, Emacs has no work to do.
The purpose of this event type is so that you can keep track of such
events if you want to.
@cindex @code{deiconify-frame} event
@item (deiconify-frame (@var{frame}))
This kind of event indicates that the user deiconified @var{frame} using
the window manager. Its standard definition is @code{ignore}; since the
frame has already been iconified, Emacs has no work to do.
@end table
@node Event Examples
@subsection Event Examples
@ -1835,6 +1870,9 @@ If @var{nodisp} is non-@code{nil}, then @code{sit-for} does not
redisplay, but it still returns as soon as input is available (or when
the timeout elapses).
Iconifying or deiconifying a frame makes @code{sit-for} return, because
that generates an event. @xref{Misc Events}.
The usual purpose of @code{sit-for} is to give the user time to read
text that you display.
@end defun
@ -2339,6 +2377,9 @@ encounters an error or a failing search.
@defvar last-kbd-macro
This variable is the definition of the most recently defined keyboard
macro. Its value is a string or vector, or @code{nil}.
The variable is always local to the current X terminal and cannot be
buffer-local. @xref{Multiple Displays}.
@end defvar
@defvar executing-macro
@ -2354,5 +2395,8 @@ This variable indicates whether a keyboard macro is being defined. A
command can test this variable to behave differently while a macro is
being defined. The commands @code{start-kbd-macro} and
@code{end-kbd-macro} set this variable---do not set it yourself.
The variable is always local to the current X terminal and cannot be
buffer-local. @xref{Multiple Displays}.
@end defvar

129
lispref/compile.texi
View file

@ -22,8 +22,8 @@ however, as fast as true compiled code.
In general, any version of Emacs can run byte-compiled code produced
by recent earlier versions of Emacs, but the reverse is not true. In
particular, if you compile a program with Emacs 18, you can run the
compiled code in Emacs 19, but not vice versa.
particular, if you compile a program with Emacs 19.29, the compiled
code does not run in earlier versions.
@xref{Compilation Errors}, for how to investigate errors occurring in
byte compilation.
@ -31,6 +31,8 @@ byte compilation.
@menu
* Speed of Byte-Code:: An example of speedup from byte compilation.
* Compilation Functions:: Byte compilation functions.
* Docs and Compilation:: Dynamic loading of documentation strings.
* Dynamic Loading:: Dynamic loading of individual functions.
* Eval During Compile:: Code to be evaluated when you compile.
* Byte-Code Objects:: The data type used for byte-compiled functions.
* Disassembly:: Disassembling byte-code; how to read byte-code.
@ -109,7 +111,7 @@ i.e., the compiler does not follow indirection to another symbol.
@code{byte-compile} returns the new, compiled definition of
@var{symbol}.
If @var{symbol}'s definition is a byte-code function object,
If @var{symbol}'s definition is a byte-code function object,
@code{byte-compile} does nothing and returns @code{nil}. Lisp records
only one function definition for any symbol, and if that is already
compiled, non-compiled code is not available anywhere. So there is no
@ -221,10 +223,129 @@ part of a byte-code function object, and only rarely due to an explicit
call to @code{byte-code}.
@end defun
@node Docs and Compilation
@section Documentation Strings and Compilation
@cindex dynamic loading of documentation
Functions and variables loaded from a byte-compiled file access their
documentation strings dynamically from the file whenever needed. This
saves space within Emacs, and make loading faster because the
documentation strings themselves need not be processed while loading the
file. Actual access to the documentation strings becomes slower as a
result, but this normally is not enough to bother users.
Dynamic access to documentation strings does have drawbacks:
@itemize @bullet
@item
If you delete or move the compiled file after loading it, Emacs can no
longer access the documentation strings for the functions and variables
in the file.
@item
If you alter the compiled file (such as by compiling a new version),
then further access to documentation strings in this file will give
nonsense results.
@end itemize
If your site installs Emacs following the usual procedures, these
problems will never normally occur. Installing a new version uses a new
directory with a different name; as long as the old version remains
installed, its files will remain unmodified in the places where they are
expected to be.
However, if you have build Emacs yourself and use it from the
directory where you built it, you will experience this problem
occasionally if you edit and recompile Lisp files. When it happens, you
can cure the problem by reloading the file after recompiling it.
Byte-compiled files made with Emacs 19.29 will not load into older
versions because the older versions don't support this feature. You can
turn off this feature by setting @code{byte-compile-dynamic-docstrings}
to @code{nil}. Once this is done, you can compile files that will load
into older Emacs versions. You can do this globally, or for one source
file by specifying a file-local binding for the variable. Here's one
way:
@example
-*-byte-compile-dynamic-docstrings: nil;-*-
@end example
@defvar byte-compile-dynamic-docstrings
If this is non-@code{nil}, the byte compiler generates compiled files
that are set up for dynamic loading of documentation strings.
@end defvar
@cindex @samp{#@@@var{count}}
@cindex @samp{#$}
The dynamic documentation string feature writes compiled files that
use a special Lisp reader construct, @samp{#@@@var{count}}. This
construct skips the next @var{count} characters. It also uses the
@samp{#$} construct, which stands for ``the name of this file, as a
string.'' It is best not to use these constructs in Lisp source files.
@node Dynamic Loading
@section Dynamic Loading of Individual Functions
@cindex dynamic loading of functions
@cindex lazy loading
When you compile a file, you can optionally enable the @dfn{dynamic
function loading} feature (also known as @dfn{lazy loading}). With
dynamic function loading, loading the file doesn't fully read the
function definitions in the file. Instead, each function definition
contains a place-holder which refers to the file. The first time each
function is called, it reads the full definition from the file, to
replace the place-holder.
The advantage of dynamic function loading is that loading the file
becomes much faster. This is a good thing for a file which contains
many separate commands, provided that using one of them does not imply
you will soon (or ever) use the rest. A specialized mode which provides
many keyboard commands often has that usage pattern: a user may invoke
the mode, but use only a few of the commands it provides.
The dynamic loading feature has certain disadvantages:
@itemize @bullet
@item
If you delete or move the compiled file after loading it, Emacs can no
longer load the remaining function definitions not already loaded.
@item
If you alter the compiled file (such as by compiling a new version),
then trying to load any function not already loaded will get nonsense
results.
@end itemize
If you compile a new version of the file, the best thing to do is
immediately load the new compiled file. That will prevent any future
problems.
The byte compiler uses the dynamic function loading feature if the
variable @code{byte-compile-dynamic} is non-@code{nil} at compilation
time. Do not set this variable globally, since dynamic loading is
desirable only for certain files. Instead, enable the feature for
specific source files with file-local variable bindings, like this:
@example
-*-byte-compile-dynamic: t;-*-
@end example
@defvar byte-compile-dynamic
If this is non-@code{nil}, the byte compiler generates compiled files
that are set up for dynamic function loading.
@end defvar
@defun fetch-bytecode function
This immediately finishes loading the definition of @var{function} from
its byte-compiled file, if it is not fully loaded already. The argument
@var{function} may be a byte-code function object or a function name.
@end defun
@node Eval During Compile
@section Evaluation During Compilation
These features permit you to write code to be evaluated during
These features permit you to write code to be evaluated during
compilation of a program.
@defspec eval-and-compile body

4
lispref/debugging.texi
View file

@ -89,6 +89,10 @@ The value can also be a list of error conditions that should call the
debugger. For example, if you set it to the list
@code{(void-variable)}, then only errors about a variable that has no
value invoke the debugger.
When this variable is non-@code{nil}, Emacs does not catch errors that
happen in process filter functions and sentinels. Therefore, these
errors also can invoke the debugger. @xref{Processes}.
@end defopt
To debug an error that happens during loading of the @file{.emacs}

201
lispref/display.texi
View file

@ -14,7 +14,8 @@ that Emacs presents to the user.
* Screen Size:: How big is the Emacs screen.
* Truncation:: Folding or wrapping long text lines.
* The Echo Area:: Where messages are displayed.
* Selective Display:: Hiding part of the buffer text.
* Invisible Text:: Hiding part of the buffer text.
* Selective Display:: Hiding part of the buffer text (the old way).
* Overlay Arrow:: Display of an arrow to indicate position.
* Temporary Displays:: Displays that go away automatically.
* Overlays:: Use overlays to highlight parts of the buffer.
@ -168,12 +169,27 @@ If it is non-@code{nil}, these lines are truncated; otherwise,
You can override the images that indicate continuation or truncation
with the display table; see @ref{Display Tables}.
If your buffer contains @strong{very} long lines, and you use
continuation to display them, just thinking about them can make Emacs
redisplay slow.
@defvar cache-long-line-scans
If this variable is non-@code{nil}, various indentation and motion
functions, and Emacs redisplay, cache the results of their scans for
newlines, and consult the cache to avoid rescanning regions of the
buffer unless they are modified.
Turning on the newline cache slows down processing of short lines.
This variable is automatically local in every buffer.
@end defvar
@node The Echo Area
@section The Echo Area
@cindex error display
@cindex echo area
The @dfn{echo area} is used for displaying messages made with the
The @dfn{echo area} is used for displaying messages made with the
@code{message} primitive, and for echoing keystrokes. It is not the
same as the minibuffer, despite the fact that the minibuffer appears
(when active) in the same place on the screen as the echo area. The
@ -187,7 +203,7 @@ functions with @code{t} as the stream (@pxref{Output Functions}), or as
follows:
@defun message string &rest arguments
This function prints a one-line message in the echo area. The
This function displays a one-line message in the echo area. The
argument @var{string} is similar to a C language @code{printf} control
string. See @code{format} in @ref{String Conversion}, for the details
on the conversion specifications. @code{message} returns the
@ -217,6 +233,21 @@ Minibuffer depth is 0.
@end example
@end defun
Almost all the messages displayed in the echo area are also recorded
in the @samp{*Messages*} buffer.
@defopt message-log-max
This variable specifies how many lines to keep in the @samp{*Messages*}
buffer. The value @code{t} means there is no limit on how many lines to
keep. The value @code{nil} disables message logging entirely. Here's
how to display a message and prevent it from being logged:
@example
(let (message-log-max)
(message @dots{}))
@end example
@end defopt
@defvar cursor-in-echo-area
This variable controls where the cursor appears when a message is
displayed in the echo area. If it is non-@code{nil}, then the cursor
@ -227,6 +258,62 @@ The value is normally @code{nil}; Lisp programs bind it to @code{t}
for brief periods of time.
@end defvar
@node Invisible Text
@section Invisible Text
@cindex invisible text
You can make characters @dfn{invisible}, so that they do not appear on
the screen, with the @code{invisible} property. This can be either a
text property or a property of an overlay.
In the simplest case, any non-@code{nil} @code{invisible} property makes
a character invisible. This is the default case---if you don't alter
the default value of @code{buffer-invisibility-spec}, this is how the
@code{invisibility} property works. This feature is much like selective
display (@pxref{Selective Display}), but more general and cleaner.
More generally, you can use the variable @code{buffer-invisibility-spec}
to control which values of the @code{invisible} property make text
invisible. This permits you to classify the text into different subsets
in advance, by giving them different @code{invisible} values, and
subsequently make various subsets visible or invisible by changing the
value of @code{buffer-invisibility-spec}.
Controlling visibility with @code{buffer-invisibility-spec} is
especially useful in a program to display the list of entries in a data
base. It permits the implementation of convenient filtering commands to
view just a part of the entries in the data base. Setting this variable
is very fast, much faster than scanning all the text in the buffer
looking for things to change.
@defvar buffer-invisibility-spec
This variable specifies which kinds of @code{invisible} properties
actually make a character invisible.
@table @asis
@item @code{t}
A character is invisible if its @code{invisible} property is
non-@code{nil}. This is the default.
@item a list
Each element of the list makes certain characters invisible.
Ultimately, a character is invisible if any of the elements of this list
applies to it. The list can have two kinds of elements:
@table @code
@item @var{atom}
A character is invisible if its @code{invisible} propery value
is @var{atom} or if it is a list with @var{atom} as a member.
@item (@var{atom} . t)
A character is invisible if its @code{invisible} propery value
is @var{atom} or if it is a list with @var{atom} as a member.
Moreover, if this character is at the end of a line and is followed
by a visible newline, it displays an ellipsis.
@end table
@end table
@end defvar
@node Selective Display
@section Selective Display
@cindex selective display
@ -237,9 +324,13 @@ lines do not appear.
The first variant, explicit selective display, is designed for use in
a Lisp program. The program controls which lines are hidden by altering
the text. Outline mode uses this variant. In the second variant, the
choice of lines to hide is made automatically based on indentation.
This variant is designed as a user-level feature.
the text. Outline mode has traditionally used this variant. It has
been partially replaced by the invisible text feature (@pxref{Invisible
Text}); there is a new version of Outline mode which uses that instead.
In the second variant, the choice of lines to hide is made
automatically based on indentation. This variant is designed as a
user-level feature.
The way you control explicit selective display is by replacing a
newline (control-j) with a carriage return (control-m). The text that
@ -370,12 +461,17 @@ given time.
@c now. Is it?
@end defvar
You can do the same job by creating an overlay with a
@code{before-string} property. @xref{Overlay Properties}.
@node Temporary Displays
@section Temporary Displays
Temporary displays are used by commands to put output into a buffer
and then present it to the user for perusal rather than for editing.
Many of the help commands use this feature.
Many of the help commands use this feature. Nowadays you can do the
same job by creating an overlay with a @code{before-string} property.
@xref{Overlay Properties}.
@defspec with-output-to-temp-buffer buffer-name forms@dots{}
This function executes @var{forms} while arranging to insert any
@ -527,11 +623,18 @@ what they should mean.
If the @code{window} property is non-@code{nil}, then the overlay
applies only on that window.
@item category
@kindex category @r{(overlay property)}
If an overlay has a @code{category} property, we call it the
@dfn{category} of the character. It should be a symbol. The properties
of the symbol serve as defaults for the properties of the overlay.
@item face
@kindex face @r{(overlay property)}
This property controls the font and color of text. @xref{Faces}, for
more information. This feature is temporary; in the future, we may
replace it with other ways of specifying how to display text.
This property controls the font and color of text. Its value is a face
name or a list of face names. @xref{Faces}, for more information. This
feature may be temporary; in the future, we may replace it with other
ways of specifying how to display text.
@item mouse-face
@kindex mouse-face @r{(overlay property)}
@ -543,39 +646,67 @@ the range of the overlay. This feature may be temporary, like
@kindex modification-hooks @r{(overlay property)}
This property's value is a list of functions to be called if any
character within the overlay is changed or if text is inserted strictly
within the overlay. Each function receives three arguments: the
overlay, and the beginning and end of the part of the buffer being
within the overlay.
The hook functions are called both before and after each change.
If the functions save the information they receive, and compare notes
between calls, they can determine exactly what change has been made
in the buffer text.
When called before a change, each function receives four arguments: the
overlay, @code{nil}, and the beginning and end of the text range to be
modified.
When called after a change, each function receives five arguments: the
overlay, @code{t}, the beginning and end of the text range just
modified, and the length of the pre-change text replaced by that range.
(For an insertion, the pre-change length is zero; for a deletion, that
length is the number of characters deleted, and the post-change
beginning and end are at the same place.)
@item insert-in-front-hooks
@kindex insert-in-front-hooks @r{(overlay property)}
This property's value is a list of functions to be called
if text is inserted right at the beginning of the overlay.
This property's value is a list of functions to be called before and
after inserting text right at the beginning of the overlay. The calling
conventions are the same as for the @code{modification-hooks} functions.
@item insert-behind-hooks
@kindex insert-behind-hooks @r{(overlay property)}
This property's value is a list of functions to be called if text is
inserted right at the end of the overlay.
This property's value is a list of functions to be called before and
after inserting text right at the end of the overlay. The calling
conventions are the same as for the @code{modification-hooks} functions.
@item invisible
@kindex invisible @r{(overlay property)}
A non-@code{nil} @code{invisible} property means that the text in the
overlay does not appear on the screen. This works much like selective
display. Details of this feature are likely to change in future
versions, so check the @file{etc/NEWS} file in the version you are
using.
The @code{invisible} property can make the text in the overlay
invisible, which means that it does not appear on the screen.
@xref{Invisible Text}, for details.
@item intangible
@kindex intangible @r{(overlay property)}
The @code{intangible} property on an overlay works just like the
@code{intangible} text propert. @xref{Special Properties}, for details.
@item before-string
@kindex before-string @r{(overlay property)}
This property's value is a string to add to the display at the beginning
of the overlay. The string does not appear in the buffer in any
sense---only on the screen. This is not yet implemented, but will be.
sense---only on the screen. The string should contain only characters
that display as a single column---control characters, including tabs or
newlines, will give strange results.
@item after-string
@kindex after-string @r{(overlay property)}
This property's value is a string to add to the display at the end of
the overlay. The string does not appear in the buffer in any
sense---only on the screen. This is not yet implemented, but will be.
sense---only on the screen. The string should contain only characters
that display as a single column---control characters, including tabs or
newlines, will give strange results.
@item evaporate
@kindex evaporate @r{(overlay property)}
If this property is non-@code{nil}, the overlay is deleted automatically
if it ever becomes empty (i.e., if it spans no characters).
@end table
These are the functions for reading and writing the properties of an
@ -583,8 +714,10 @@ overlay.
@defun overlay-get overlay prop
This function returns the value of property @var{prop} recorded in
@var{overlay}. If @var{overlay} does not record any value for that
property, then the value is @code{nil}.
@var{overlay}, if any. If @var{overlay} does not record any value for
that property, but it does have a @code{category} property which is a
symbol, that symbol's @var{prop} property is used. Otherwise, the value
is @code{nil}.
@end defun
@defun overlay-put overlay prop value
@ -654,6 +787,11 @@ This function returns the buffer position of the next beginning or end
of an overlay, after @var{pos}.
@end defun
@defun previous-overlay-change pos
This function returns the buffer position of the previous beginning or
end of an overlay, before @var{pos}.
@end defun
@node Faces
@section Faces
@cindex face
@ -667,6 +805,12 @@ Each face has its own @dfn{face id number} which distinguishes faces at
low levels within Emacs. However, for most purposes, you can refer to
faces in Lisp programs by their names.
@defun facep object
This function returns @code{t} if @var{object} is a face name symbol (or
if it is a vector of the kind used internally to record face data). It
returns @code{nil} otherwise.
@end defun
Each face name is meaningful for all frames, and by default it has the
same meaning in all frames. But you can arrange to give a particular
face name a special meaning in one frame if you wish.
@ -1051,9 +1195,10 @@ This creates and returns a display table. The table initially has
element says how to display the character code @var{n}. The value
should be @code{nil} or a vector of glyph values (@pxref{Glyphs}). If
an element is @code{nil}, it says to display that character according to
the usual display conventions (@pxref{Usual Display}). Note that the
display table has no effect on the tab and newline characters; they are
always displayed as whitespace in their usual special fashion.
the usual display conventions (@pxref{Usual Display}).
If you use the display table to change the display of newline
characters, the whole buffer will be displayed as one long ``line.''
The remaining six elements of a display table serve special purposes,
and @code{nil} means use the default stated below.

27
lispref/elisp.texi
View file

@ -6,8 +6,8 @@
@c %**end of header
@ifinfo
This version is the edition 2.3 of the GNU Emacs Lisp
Reference Manual. It corresponds to Emacs Version 19.25.
This version is the edition 2.4 of the GNU Emacs Lisp
Reference Manual. It corresponds to Emacs Version 19.29.
@c Please REMEMBER to update edition number in *four* places in this file
@c and also in *one* place in intro.texi
@ -15,7 +15,7 @@ Published by the Free Software Foundation
675 Massachusetts Avenue
Cambridge, MA 02139 USA
Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software Foundation, Inc.
Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
@ -68,21 +68,20 @@ instead of in the original English.
@subtitle for Unix Users
@c The edition number appears in several places in this file
@c and also in the file intro.texi.
@subtitle Second Edition, June 1993
@subtitle Revision 2.3, June 1994
@subtitle Revision 2.4, June 1995
@author by Bil Lewis, Dan LaLiberte, Richard Stallman
@author and the GNU Manual Group
@page
@vskip 0pt plus 1filll
Copyright @copyright{} 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
Copyright @copyright{} 1990, 1991, 1992, 1993, 1994, 1995 Free Software Foundation, Inc.
@sp 2
Edition 2.3 @*
Revised for Emacs Version 19.25,@*
June, 1994.@*
Edition 2.4 @*
Revised for Emacs Version 19.29,@*
June, 1995.@*
@sp 2
ISBN 1-882114-40-X
ISBN 1-882114-71-X
@sp 2
Published by the Free Software Foundation @*
@ -113,8 +112,8 @@ Cover art by Etienne Suvasa.
@node Top, Copying, (dir), (dir)
@ifinfo
This Info file contains edition 2.3 of the GNU Emacs Lisp
Reference Manual, corresponding to GNU Emacs version 19.25.
This Info file contains edition 2.4 of the GNU Emacs Lisp
Reference Manual, corresponding to GNU Emacs version 19.29.
@end ifinfo
@menu
@ -268,7 +267,7 @@ Numbers
* Arithmetic Operations:: How to add, subtract, multiply and divide.
* Bitwise Operations:: Logical and, or, not, shifting.
* Numeric Conversions:: Converting float to integer and vice versa.
* Transcendental Functions:: Trig, exponential and logarithmic functions.
* Math Functions:: Trig, exponential and logarithmic functions.
* Random Numbers:: Obtaining random integers, predictable or not.
Strings and Characters
@ -707,7 +706,7 @@ The Kill Ring
* Kill Ring Concepts:: What text looks like in the kill ring.
* Kill Functions:: Functions that kill text.
* Yank Commands:: Commands that access the kill ring.
* Low Level Kill Ring:: Functions and variables for kill ring access.
* Low-Level Kill Ring:: Functions and variables for kill ring access.
* Internals of Kill Ring:: Variables that hold kill-ring data.
Indentation

4
lispref/eval.texi
View file

@ -165,6 +165,10 @@ reached, or until an error is signaled and not handled.
If @var{stream} is supplied, @code{standard-output} is bound to it
during the evaluation.
You can use the variable @code{load-read-function} to specify a function
for @code{eval-region} to use instead of @code{read} for reading
expressions. @xref{How Programs Do Loading}.
@code{eval-region} always returns @code{nil}.
@end deffn

144
lispref/files.texi
View file

@ -34,6 +34,7 @@ substitutions such as @samp{$HOME}. @xref{File Name Expansion}.
* Create/Delete Dirs:: Creating and Deleting Directories.
* Magic File Names:: Defining "magic" special handling
for certain file names.
* Format Conversion:: Conversion to and from various file formats.
* Files and MS-DOS:: Distinguishing text and binary files on MS-DOS.
@end menu
@ -426,6 +427,10 @@ contents of the buffer (actually, just the accessible portion) with the
contents of the file. This is better than simply deleting the buffer
contents and inserting the whole file, because (1) it preserves some
marker positions and (2) it puts less data in the undo list.
The function @code{insert-file-contents} checks the file contents
against the defined file formats, and converts the file contents if
appropriate. @xref{Format Conversion}.
@end defun
If you want to pass a file name to another process so that another
@ -488,6 +493,10 @@ Normally, @code{write-region} displays a message @samp{Wrote file
nor @code{nil} nor a string, then this message is inhibited. This
feature is useful for programs that use files for internal purposes,
files that the user does not need to know about.
The function @code{write-region} converts the data which it writes to
the appropriate file formats specified by @code{buffer-file-format}.
@xref{Format Conversion}.
@end deffn
@node File Locks
@ -684,6 +693,11 @@ we can deduce that any attempt to read a file in @file{/foo/} will
give an error.
@end defun
@defun file-ownership-preserved-p filename
This function returns @code{t} if deleting the file @var{filename} and
then creating it anew would keep the file's owner unchanged.
@end defun
@defun file-newer-than-file-p filename1 filename2
@cindex file age
@cindex file modification time
@ -787,6 +801,12 @@ existing directory, @code{nil} otherwise.
@end example
@end defun
@defun file-regular-p filename
This function returns @code{t} if the file @var{filename} exists and is
a regular file (not a directory, symbolic link, named pipe, terminal, or
other I/O device).
@end defun
@node Truenames
@subsection Truenames
@cindex truename (of file)
@ -1309,6 +1329,12 @@ backup version numbers, or trailing tildes.
@end example
@end defun
@defun file-name-sans-extension filename
This function returns @var{filename} sans its final ``extension'', if
any. The extension, in a file name, is the part that follows the last
@samp{.}.
@end defun
@node Directory Names
@comment node-name, next, previous, up
@subsection Directory Names
@ -1944,6 +1970,124 @@ non-magic directory to serve as its current directory, and this function
is a good way to come up with one.
@end defun
@node Format Conversion
@section File Format Conversion
@cindex file format conversion
@cindex encoding file formats
@cindex decoding file formats
The variable @code{format-alist} defines a list of @dfn{file formats},
which are textual representations used in files for the data (text,
text-properties, and possibly other information) in an Emacs buffer.
Emacs performs format conversion when reading and writing files.
@defvar format-alist
This list contains one format definition for each defined file format.
@end defvar
@cindex format definition
Each format definition is a list of this form:
@example
(@var{name} @var{doc-string} @var{regexp} @var{from-fn} @var{to-fn} @var{modify} @var{mode-fn})
@end example
Here is what the elements in a format definition mean:
@table @var
@item name
The name of this format.
@item doc-string
A documentation string for the format.
@item regexp
A regular expression which is used to recognize files represented in
this format.
@item from-fn
A function to call to decode data in this format (to convert file data into
the usual Emacs data representation).
The @var{from-fn} is called with two args, @var{begin} and @var{end},
which specify the part of the buffer it should convert. It should convert
the text by editing it in place. Since this can change the length of the
text, @var{from-fn} should return the modified end position.
One responsibility of @var{from-fm} is to make sure that the beginning
of the file no longer matches @var{regexp}. Otherwise it is likely to
get called again.
@item to-fn
A function to call to encode data in this format (to convert
the usual Emacs data representation into this format).
The @var{to-fn} is called with two args, @var{begin} and @var{end},
which specify the part of the buffer it should convert. There are
two ways it can do the conversion:
@itemize @bullet
@item
By editing the buffer in place. In this case, @var{to-fn} should
return the end-position of the range of text, as modified.
@item
By returning a list of annotations. This is a list of elements of the
form @code{(@var{position} . @var{string})}, where @var{position} is an
integer specifying the relative position in the text to be written, and
@var{string} is the annotation to add there. The list must be sorted in
order of position when @var{to-fn} returns it.
When @code{write-region} actually writes the text from the buffer to the
file, it intermixes the specified annotations at the corresponding
positions. All this takes place without modifying the buffer.
@end itemize
@item modify
A flag, @code{t} if the encoding function modifies the buffer, and
@code{nil} if it works by returning a list of annotations.
@item mode
A mode function to call after visiting a file converted from this
format.
@end table
The function @code{insert-file-contents} automatically recognizes file
formats when it reads the specified file. It checks the text of the
beginning of the file against the regular expressions of the format
definitions, and if it finds a match, it calls the decoding function for
that format. Then it checks all the known formats over again.
It keeps checking them until none of them is applicable.
Visiting a file, with @code{find-file-noselect} or the commands that use
it, performs conversion likewise (because it calls
@code{insert-file-contents}); but it also calls the mode function for
each format that it decodes. It stores a list of the format names
in the buffer-local variable @code{buffer-file-format}.
@defvar buffer-file-format
This variable holds a list of the file formats that were decoded in the
course of visiting the current buffer's file. It is always local in all
buffers.
@end defvar
When @code{write-region} writes data into a file, it first calls the
encoding functions for the formats listed in @code{buffer-file-format}.
@defun format-write-file file format
This command writes the current buffer contents into the file @var{file}
in format @var{format}, and makes that format the default for future
saves of the buffer.
@end defun
@defvar auto-save-file-format
This variable specifies the format to use for auto-saving. Its value is
a list of format names, just like the value of
@code{buffer-file-format}; but it is used instead of
@code{buffer-file-format} for writing auto-save files. This variable
is always local in all buffers.
@end defvar
@node Files and MS-DOS
@section Files and MS-DOS
@cindex MS-DOS file types

333
lispref/frames.texi
View file

@ -14,11 +14,13 @@ horizontally into smaller windows.
@cindex terminal frame
@cindex X window frame
When Emacs runs on a text-only terminal, it has just one frame, a
@dfn{terminal frame}. There is no way to create another terminal frame
after startup. If Emacs has an X display, it does not have a terminal
frame; instead, it starts with a single @dfn{X window frame}. You can
create more; see @ref{Creating Frames}.
When Emacs runs on a text-only terminal, it starts with one
@dfn{terminal frames}. If you create additional ones, Emacs displays
one and only one at any given time---on the terminal screen, of course.
When Emacs uses X for display, it does not have a terminal frame;
instead, it starts with a single @dfn{X window frame}. It can display
multiple X window frames at the same time, each in its own X window.
@defun framep object
This predicate returns @code{t} if @var{object} is a frame, and
@ -26,8 +28,10 @@ This predicate returns @code{t} if @var{object} is a frame, and
@end defun
@menu
* Creating Frames:: Creating additional X Window frames.
* Creating Frames:: Creating additional frames.
* Multiple Displays:: Creating frames on other X displays.
* Frame Parameters:: Controlling frame size, position, font, etc.
* Frame Titles:: Automatic updating of frame titles.
* Deleting Frames:: Frames last until explicitly deleted.
* Finding All Frames:: How to examine all existing frames.
* Frames and Windows:: A frame contains windows;
@ -57,8 +61,8 @@ This predicate returns @code{t} if @var{object} is a frame, and
To create a new frame, call the function @code{make-frame}.
@defun make-frame alist
This function creates a new frame, if the display mechanism permits
creation of frames. (An X server does; an ordinary terminal does not.)
This function creates a new frame. If you are using X, it makes
an X window frame; otherwise, it makes a terminal frame.
The argument is an alist specifying frame parameters. Any parameters
not mentioned in @var{alist} default according to the value of the
@ -67,8 +71,7 @@ either default from the standard X defaults file and X resources.
The set of possible parameters depends in principle on what kind of
window system Emacs uses to display its frames. @xref{X Frame
Parameters}, for documentation of individual parameters you can specify
when creating an X window frame.
Parameters}, for documentation of individual parameters you can specify.
@end defun
@defvar before-make-frame-hook
@ -80,6 +83,62 @@ frame.
A normal hook run by @code{make-frame} after it creates the frame.
@end defvar
@node Multiple Displays
@section Multiple Displays
@cindex multiple displays
@cindex multiple X terminals
@cindex displays, multiple
A single Emacs can talk to more than one X Windows 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
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}, @code{multiple-frames} and
@code{system-key-alist}. These variables are always terminal-local and
can never be buffer-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
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
terminal.
@deffn Command make-frame-on-display display &optional parameters
This creates a new frame on display @var{display}, taking the other
frame parameters from @var{parameters}. Aside from the @var{display}
argument, it is like @code{make-frame} (@pxref{Creating Frames}).
@end deffn
@defun x-display-list
This returns a list that indicates which X displays Emacs has a
connection to. The elements of the list are display names (strings).
@end defun
@defun x-open-connection display &optional xrm-string
This function opens a connection to the X display @var{display}. It
does not create a frame on that display, but it permits you to check
that communication can be established with that display.
The optional second argument @var{xrm-string} should be a string of
resources in xrdb format, or @code{nil}. The resources, if specified,
apply to all Emacs frames created on this display.
@end defun
@defun x-close-connection display
This function closes the connection to display @var{display}. Before
you can do this, you must first delete all the frames that were open on
that display (@pxref{Deleting Frames}).
@end defun
@node Frame Parameters
@section Frame Parameters
@ -95,7 +154,7 @@ and width.
@menu
* Parameter Access:: How to change a frame's parameters.
* Initial Parameters:: Specifying frame parameters when you make a frame.
* X Frame Parameters:: Individual parameters documented.
* X Frame Parameters:: List of frame parameters.
* Size and Position:: Changing the size and position of a frame.
@end menu
@ -180,7 +239,9 @@ instead. @xref{Command Arguments,,, emacs, The GNU Emacs Manual}.
@subsection X Window Frame Parameters
Just what parameters a frame has depends on what display mechanism it
uses. Here is a table of the parameters of an X window frame:
uses. Here is a table of the parameters of an X window frame; of these,
@code{name}, @code{height}, @code{width}, and @code{buffer-predicate}
provide meaningful information in non-X frames.
@table @code
@item name
@ -193,15 +254,32 @@ If you specify the frame name explicitly when you create the frame, the
name is also used (instead of the name of the Emacs executable) when
looking up X resources for the frame.
@item display
The display on which to open this frame. It should be a string of the
form @code{"@var{host}:@var{dpy}.@var{screen}"}, just like the
@code{DISPLAY} environment variable.
@item left
The screen position of the left edge, in pixels. The value may be
@code{-} instead of a number; that represents @samp{-0} in a geometry
specification.
The screen position of the left edge, in pixels, with respect to the
left edge of the screen. The value may be a positive number @var{pos},
or a list of the form @code{(+ @var{pos})} which permits specifying a
negative @var{pos} value.
A negative number @minus{}@var{pos}, or a list of the form @code{(-
@var{pos})}, actually specifies the position of the right edge of the
window with respect to the right edge of the screen, counting toward the
left.
@item top
The screen position of the top edge, in pixels. The value may be
@code{-} instead of a number; that represents @samp{-0} in a geometry
specification.
The screen position of the top edge, in pixels, with respect to the
top edge of the screen. The value may be a positive number @var{pos},
or a list of the form @code{(+ @var{pos})} which permits specifying a
negative @var{pos} value.
A negative number @minus{}@var{pos}, or a list of the form @code{(-
@var{pos})}, actually specifies the position of the bottom edge of the
window with respect to the bottom edge of the screen, counting toward the
top.
@item icon-left
The screen position of the left edge @emph{of the frame's icon}, in
@ -237,6 +315,14 @@ yes, @code{nil} means no, @code{only} means this frame is just a
minibuffer, a minibuffer window (in some other frame) means the new
frame uses that minibuffer.
@item buffer-predicate
The buffer-predicate function for this frame. The function
@code{other-buffer} uses this predicate (from the selected frame) to
decide which buffers it should consider, if the predicate is not
@code{nil}. It calls the predicate with one arg, a buffer, once for
each buffer; if the predicate returns a non-@code{nil} value, it
considers that buffer.
@item font
The name of the font for displaying text in the frame. This is a
string.
@ -256,6 +342,9 @@ Whether the frame has scroll bars for horizontal scrolling
(non-@code{nil} means yes). (Horizontal scroll bars are not currently
implemented.)
@item scroll-bar-width
The width of the vertical scroll bar, in pixels.
@item icon-type
The type of icon to use for this frame when it is iconified. If the
value is a string, that specifies a file containing a bitmap to use.
@ -279,11 +368,12 @@ The color for the cursor that shows point.
The color for the border of the frame.
@item cursor-type
The way to display the cursor. There are two legitimate values:
@code{bar} and @code{box}. The symbol @code{bar} specifies a vertical
bar between characters as the cursor. The symbol @code{box} specifies
an ordinary black box overlaying the character after point; that is the
default.
The way to display the cursor. The legitimate values are @code{bar},
@code{box}, and @code{(bar . @var{width})}. The symbol @code{box}
specifies an ordinary black box overlaying the character after point;
that is the default. The symbol @code{bar} specifies a vertical bar
between characters as the cursor. @code{(bar . @var{width})} specifies
a bar @var{width} pixels wide.
@item border-width
The width in pixels of the window border.
@ -376,9 +466,37 @@ gives the values specified for them. Each element looks like
@code{(@var{parameter} . @var{value})}. The possible @var{parameter}
values are @code{left}, @code{top}, @code{width}, and @code{height}.
For the size parameters, the value must be an integer. The position
parameter names @code{left} and @code{top} are not totally accurate,
because some values indicate the position of the right or bottom edges
instead. These are the @var{value} possibilities for the position
parameters:
@table @asis
@item an integer
A positive integer relates the left edge or top edge of the window to
the left or top edge of the screen. A negative integer relates the
right or bottom edge of the window to the right or bottom edge of the
screen.
@item (+ @var{position})
This specifies the position of the left or top edge of the window
relative to the left or top edge of the screen. The integer
@var{position} may be positive or negative; a negative value specifies a
position outside the screen.
@item (- @var{position})
This specifies the position of the right or bottom edge of the window
relative to the right or bottom edge of the screen. The integer
@var{position} may be positive or negative; a negative value specifies a
position outside the screen.
@end table
Here is an example:
@smallexample
(x-parse-geometry "35x70+0-0")
@result{} ((width . 35) (height . 70) (left . 0) (top . -1))
@result{} ((width . 35) (height . 70) (left . 0) (top - 0))
@end smallexample
@end defun
@ -388,6 +506,42 @@ size of a specified frame. The frame is the first argument; the size is
the second.
@end ignore
@node Frame Titles
@section Frame Titles
Every frame has a title; most window managers display the frame title at
the top of the frame. You can specify an explicit title with the
@code{name} frame property. But normally you don't specify this
explicitly, and Emacs computes the title automatically.
Emacs computes the frame title based on a template stored in the
variable @code{frame-title-format}.
@defvar frame-title-format
This variable specifies how to compute a title for a frame
when you have not explicitly specified one.
The variable's value is actually a mode line construct, just like
@code{mode-line-format}. @xref{Mode Line Data}.
@end defvar
@defvar icon-title-format
This variable specifies how to compute the title for an iconified frame,
when you have not explicitly specified the frame title. This title
appears in the icon itself.
@end defvar
@defvar multiple-frames
This variable is set automatically by Emacs. Its value is @code{t} when
there are two or more frames (not counting minibuffer-only frames or
invisible frames). The default value of @code{frame-title-format} uses
@code{multiple-frames} so as to put the buffer name in the frame title
only when there is more than one frame.
The variable is always local to the current X terminal and cannot be
buffer-local. @xref{Multiple Displays}.
@end defvar
@node Deleting Frames
@section Deleting Frames
@cindex deletion of frames
@ -409,6 +563,12 @@ The function @code{frame-live-p} returns non-@code{nil} if the frame
@var{frame} has not been deleted.
@end defun
Some window managers provide a command to delete a window. These work
by sending a special message to the program than operates the window.
When Emacs gets one of these commands, it generates a
@code{delete-frame} event, whose normal definition is a command that
calls the function @code{delete-frame}. @xref{Misc Events}.
@node Finding All Frames
@section Finding All Frames
@ -421,7 +581,8 @@ doesn't have any effect on the internals of Emacs.
@defun visible-frame-list
This function returns a list of just the currently visible frames.
@xref{Visibility of Frames}.
@xref{Visibility of Frames}. (Terminal frames always count as
``visible'', even though only the selected one is actually displayed.)
@end defun
@defun next-frame &optional frame minibuf
@ -502,6 +663,12 @@ If you use a minibuffer-only frame, you might want that frame to raise
when you enter the minibuffer. If so, set the variable
@code{minibuffer-auto-raise} to @code{t}. @xref{Raising and Lowering}.
@defvar default-minibuffer-frame
This variable specifies the frame to use for the minibuffer window, by
default. It is always local to the current X terminal and cannot be
buffer-local. @xref{Multiple Displays}.
@end defvar
@node Input Focus
@section Input Focus
@cindex input focus
@ -524,12 +691,20 @@ the function @code{select-frame}. This does not override the window
manager; rather, it escapes from the window manager's control until
that control is somehow reasserted.
When using a text-only terminal, there is no window manager; therefore,
@code{switch-frame} is the only way to switch frames, and the effect
lasts until overridden by a subsequent call to @code{switch-frame}.
Only the selected terminal frame is actually displayed on the terminal.
Each terminal screen except for the initial one has a number, and the
number of the selected frame appears in the mode line after the word
@samp{Emacs}.
@c ??? This is not yet implemented properly.
@defun select-frame frame
This function selects frame @var{frame}, temporarily disregarding the
focus of the X server. The selection of @var{frame} lasts until the
next time the user does something to select a different frame, or until
the next time this function is called.
focus of the X server if any. The selection of @var{frame} lasts until
the next time the user does something to select a different frame, or
until the next time this function is called.
@end defun
Emacs cooperates with the X server and the window managers by arranging
@ -583,10 +758,14 @@ change it.
@cindex iconified frame
@cindex frame visibility
A frame may be @dfn{visible}, @dfn{invisible}, or @dfn{iconified}. If
it is visible, you can see its contents. If it is iconified, the
frame's contents do not appear on the screen, but an icon does. If the
frame is invisible, it doesn't show on the screen, not even as an icon.
An X windo frame may be @dfn{visible}, @dfn{invisible}, or
@dfn{iconified}. If it is visible, you can see its contents. If it is
iconified, the frame's contents do not appear on the screen, but an icon
does. If the frame is invisible, it doesn't show on the screen, not
even as an icon.
Visibility is meaningless for terminal frames, since only the selected
one is actually displayed in any case.
@deffn Command make-frame-visible &optional frame
This function makes frame @var{frame} visible. If you omit @var{frame},
@ -613,6 +792,11 @@ This returns the visibility status of frame @var{frame}. The value is
parameter. You can read or change it as such. @xref{X Frame
Parameters}.
The user can iconify and deiconify frames with the window manager.
This happens below the level at which Emacs can exert any control, but
Emacs does provide events that you can use to keep track of such
changes. @xref{Misc Events}.
@node Raising and Lowering
@section Raising and Lowering Frames
@ -634,13 +818,13 @@ screen.
You can raise and lower Emacs's X windows with these functions:
@defun raise-frame frame
@deffn Command raise-frame frame
This function raises frame @var{frame}.
@end defun
@end deffn
@defun lower-frame frame
@deffn Command lower-frame frame
This function lowers frame @var{frame}.
@end defun
@end deffn
@defopt minibuffer-auto-raise
If this is non-@code{nil}, activation of the minibuffer raises the frame
@ -771,6 +955,9 @@ characters. These coordinates are not required to be within the frame.
@node Pop-Up Menus
@section Pop-Up Menus
When using X windows, a Lisp program can pop up a menu which the
user can choose from with the mouse.
@defun x-popup-menu position menu
This function displays a pop-up menu and returns an indication of
what selection the user makes.
@ -873,8 +1060,8 @@ pop-up menu in the center of the frame.
@cindex pointer shape
@cindex mouse pointer shape
These variables specify which mouse pointer shape to use in various
situations:
These variables specify which shape to use for the mouse pointer in
various situations:
@table @code
@item x-pointer-shape
@ -1072,68 +1259,74 @@ If you specify them, the key is
@section Data about the X Server
This section describes functions and a variable that you can use to
get information about the capabilities and origin of the X server that
Emacs is displaying its frames on.
get information about the capabilities and origin of an X display that
Emacs is using. Each of these functions lets you specify the display
you are interested in: the @var{display} argument can be either a
display name, or a frame (meaning use the display that frame is on). If
you omit the @var{display} argument, that means to use the selected
frame's display.
@defun x-display-screens
This function returns the number of screens associated with the current
display.
@defun x-display-screens &optional display
This function returns the number of screens associated with the display.
@end defun
@defun x-server-version
This function returns the list of version numbers of the X server in
use.
@defun x-server-version &optional display
This function returns the list of version numbers of the X server
running the display.
@end defun
@defun x-server-vendor
This function returns the vendor supporting the X server in use.
@defun x-server-vendor &optional display
This function returns the vendor that provided the X server software.
@end defun
@defun x-display-pixel-height
This function returns the height of this X screen in pixels.
@defun x-display-pixel-height &optional display
This function returns the height of the screen in pixels.
@end defun
@defun x-display-mm-height
This function returns the height of this X screen in millimeters.
@defun x-display-mm-height &optional display
This function returns the height of the screen in millimeters.
@end defun
@defun x-display-pixel-width
This function returns the width of this X screen in pixels.
@defun x-display-pixel-width &optional display
This function returns the width of the screen in pixels.
@end defun
@defun x-display-mm-width
This function returns the width of this X screen in millimeters.
@defun x-display-mm-width &optional display
This function returns the width of the screen in millimeters.
@end defun
@defun x-display-backing-store
This function returns the backing store capability of this screen.
@defun x-display-backing-store &optional display
This function returns the backing store capability of the screen.
Values can be the symbols @code{always}, @code{when-mapped}, or
@code{not-useful}.
@end defun
@defun x-display-save-under
This function returns non-@code{nil} if this X screen supports the
@defun x-display-save-under &optional display
This function returns non-@code{nil} if the display supports the
SaveUnder feature.
@end defun
@defun x-display-planes
This function returns the number of planes this display supports.
@defun x-display-planes &optional display
This function returns the number of planes the display supports.
@end defun
@defun x-display-visual-class
This function returns the visual class for this X screen. The value is
one of the symbols @code{static-gray}, @code{gray-scale},
@defun x-display-visual-class &optional display
This function returns the visual class for the screen. The value is one
of the symbols @code{static-gray}, @code{gray-scale},
@code{static-color}, @code{pseudo-color}, @code{true-color}, and
@code{direct-color}.
@end defun
@defun x-display-color-p
This function returns @code{t} if the X screen in use is a color
screen.
@defun x-display-grayscale-p &optional display
This function returns @code{t} if the screen can display shades of gray.
@end defun
@defun x-display-color-cells
This function returns the number of color cells this X screen supports.
@defun x-display-color-p &optional display
This function returns @code{t} if the screen is a color screen.
@end defun
@defun x-display-color-cells &optional display
This function returns the number of color cells the screen supports.
@end defun
@ignore

27
lispref/keymaps.texi
View file

@ -582,6 +582,21 @@ keymap, if any, overrides all other maps that would have been active,
except for the current global map.
@end defvar
@defvar overriding-local-map-menu-flag
If this variable is non-@code{nil}, the value of
@code{overriding-local-map} can affect the display of the menu bar. The
default value is @code{nil}, so @code{overriding-local-map} has no
effect on the menu bar.
Note that @code{overriding-local-map} does affect the execution of key
sequences entered using the menu bar, even if it does not affect the
menu bar display. So if a menu bar key sequence comes in, you should
clear @code{overriding-local-map} before looking up and executing that
key sequence. Modes that use @code{overriding-local-map} would
typically do this anyway; normally they respond to events that they do
not handle by ``unreading'' them and and exiting.
@end defvar
@node Key Lookup
@section Key Lookup
@cindex key lookup
@ -913,6 +928,13 @@ containing a single @kbd{C-M-x}. You can also use this escape syntax in
vectors, as well as others that aren't allowed in strings; one example
is @samp{[?\C-\H-x home]}. @xref{Character Type}.
The key definition and lookup functions accept an alternate syntax for
event types in a key sequence that is a vector: you can use a list
containing modifier names plus one base event (a character or function
key name). For example, @code{(control ?a)} is equivalent to
@code{?\C-a} and @code{(hyper control left)} is equivalent to
@code{C-H-left}.
For the functions below, an error is signaled if @var{keymap} is not a
keymap or if @var{key} is not a string or vector representing a key
sequence. You can use event types (symbols) as shorthand for events
@ -1585,6 +1607,11 @@ that menu bar item, it brings up a single, combined submenu containing
all the subcommands of that item---the global subcommands, the local
subcommands, and the minor mode subcommands, all together.
The variable @code{overriding-local-map} is normally ignored when
determining the menu bar contents. That is, the menu bar is computed
from the keymaps that would be active if @code{overriding-local-map}
were @code{nil}. @xref{Active Keymaps}.
In order for a frame to display a menu bar, its @code{menu-bar-lines}
parameter must be greater than zero. Emacs uses just one line for the
menu bar itself; if you specify more than one line, the other lines

46
lispref/lists.texi
View file

@ -554,34 +554,14 @@ not a list, the sequence's elements do not become elements of the
resulting list. Instead, the sequence becomes the final @sc{cdr}, like
any other non-list final argument.
Integers are also allowed as arguments to @code{append}. They are
converted to strings of digits making up the decimal print
representation of the integer, and these strings are then appended.
Here's what happens:
@example
@group
(setq trees '(pine oak))
@result{} (pine oak)
@end group
@group
(char-to-string 54)
@result{} "6"
@end group
@group
(setq longer-list (append trees 6 '(spruce)))
@result{} (pine oak 54 spruce)
@end group
@group
(setq x-list (append trees 6 6))
@result{} (pine oak 54 . 6)
@end group
@end example
This special case exists for compatibility with Mocklisp, and we don't
recommend you take advantage of it. If you want to convert an integer
in this way, use @code{format} (@pxref{Formatting Strings}) or
@code{number-to-string} (@pxref{String Conversion}).
The @code{append} function also allows integers as arguments. It
converts them to strings of digits, making up the decimal print
representation of the integer, and then uses the strings instead of the
original integers. @strong{Don't use this feature; we plan to eliminate
it. If you already use this feature, change your programs now!} The
proper way to convert an integer to a decimal number in this way is with
@code{format} (@pxref{Formatting Strings}) or @code{number-to-string}
(@pxref{String Conversion}).
@end defun
@defun reverse list
@ -1303,6 +1283,16 @@ Here is another example, in which the keys and values are not symbols:
@end smallexample
@end defun
@defun rassoc value alist
This function returns the first association with value @var{value} in
@var{alist}. It returns @code{nil} if no association in @var{alist} has
a @sc{cdr} @code{equal} to @var{value}.
@code{rassoc} is like @code{assoc} except that it compares the @sc{cdr} of
each @var{alist} association instead of the @sc{car}. You can think of
this as ``reverse @code{assoc}'', finding the key for a given value.
@end defun
@defun assq key alist
This function is like @code{assoc} in that it returns the first
association for @var{key} in @var{alist}, but it makes the comparison

14
lispref/loading.texi
View file

@ -101,6 +101,10 @@ error @code{file-error} (with @samp{Cannot open load file
@var{filename}}). But if @var{missing-ok} is non-@code{nil}, then
@code{load} just returns @code{nil}.
You can use the variable @code{load-read-function} to specify a function
for @code{load} to use instead of @code{read} for reading expressions.
See below.
@code{load} returns @code{t} if the file loads successfully.
@end defun
@ -191,6 +195,15 @@ This variable is non-@code{nil} if Emacs is in the process of loading a
file, and it is @code{nil} otherwise. This is how @code{defun} and
@code{provide} determine whether a load is in progress, so that their
effect can be undone if the load fails.
@end defvar
@defvar load-read-function
This variable specifies an alternate expression-reading function for
@code{load} and @code{eval-region} to use instead of @code{read}.
The function should accept one argument, just as @code{read} does.
Normally, the variable's value is @code{nil}, which means those
functions should use @code{read}.
@end defvar
To learn how @code{load} is used to build Emacs, see @ref{Building Emacs}.
@ -326,7 +339,6 @@ convention used only in the preloaded Lisp files such as
documentation string in the @file{etc/DOC} file. @xref{Building Emacs}.
@node Repeated Loading
@comment node-name, next, previous, up
@section Repeated Loading
@cindex repeated loading

66
lispref/macros.texi
View file

@ -203,6 +203,7 @@ called interactively.
@section Backquote
@cindex backquote (list substitution)
@cindex ` (list substitution)
@findex `
Macros often need to construct large list structures from a mixture of
constants and nonconstant parts. To make this easier, use the macro
@ -215,11 +216,11 @@ two forms yield identical results:
@example
@group
(` (a list of (+ 2 3) elements))
`(a list of (+ 2 3) elements)
@result{} (a list of (+ 2 3) elements)
@end group
@group
(quote (a list of (+ 2 3) elements))
'(a list of (+ 2 3) elements)
@result{} (a list of (+ 2 3) elements)
@end group
@end example
@ -235,7 +236,7 @@ argument of @code{,} and puts the value in the list structure:
@result{} (a list of 5 elements)
@end group
@group
(` (a list of (, (+ 2 3)) elements))
`(a list of ,(+ 2 3) elements)
@result{} (a list of 5 elements)
@end group
@end example
@ -258,7 +259,7 @@ Here are some examples:
@result{} (1 2 3 4 2 3)
@end group
@group
(` (1 (,@@ some-list) 4 (,@@ some-list)))
`(1 ,@@some-list 4 ,@@some-list)
@result{} (1 2 3 4 2 3)
@end group
@ -273,57 +274,22 @@ Here are some examples:
@result{} (use the words foo bar as elements)
@end group
@group
(` (use the words (,@@ (cdr list)) as elements))
`(use the words ,@@(cdr list) as elements)
@result{} (use the words foo bar as elements)
@end group
@end example
Emacs 18 had a bug that made the previous example fail. The bug
affected @code{,@@} followed only by constant elements. If you are
concerned with Emacs 18 compatibility, you can work around the bug like
this:
@example
(` (use the words (,@@ (cdr list)) as elements @code{(,@@ nil)}))
@end example
@noindent
@code{(,@@ nil)} avoids the problem by being a nonconstant element that
does not affect the result.
@defmac ` list
This macro quotes @var{list} except for any sublists of the form
@code{(, @var{subexp})} or @code{(,@@ @var{listexp})}. Backquote
replaces these sublists with the value of @var{subexp} (as a single
element) or @var{listexp} (by splicing). Backquote copies the structure
of @var{list} down to the places where variable parts are substituted.
@ignore @c these work now!
There are certain contexts in which @samp{,} would not be recognized and
should not be used:
@smallexample
@group
;; @r{Use of a @samp{,} expression as the @sc{cdr} of a list.}
(` (a . (, 1))) ; @r{Not @code{(a . 1)}}
@result{} (a \, 1)
@end group
@group
;; @r{Use of @samp{,} in a vector.}
(` [a (, 1) c]) ; @r{Not @code{[a 1 c]}}
@error{} Wrong type argument
@end group
@end smallexample
@end ignore
@end defmac
@cindex CL note---@samp{,}, @samp{,@@} as functions
@quotation
@b{Common Lisp note:} In Common Lisp, @samp{,} and @samp{,@@} are
implemented as reader macros, so they do not require parentheses. In
Emacs Lisp they use function call syntax because reader macros are not
supported (for simplicity's sake).
Before Emacs version 19.29, @code{`} used a different syntax which
required an extra level of parentheses around the entire backquote
construct. Likewise, each @code{,} or @code{,@@} substition required an
extra level of parentheses surrounding both the @code{,} or @code{,@@}
and the following expression. The old syntax required whitespace
between the @code{`}, @code{,} or @code{,@@} and the following
expression.
This syntax is still accepted, but no longer recommended except for
compatibility with old Emacs versions.
@end quotation
@node Problems with Macros

20
lispref/minibuf.texi
View file

@ -554,7 +554,7 @@ too short). Both of those begin with the string @samp{foobar}.
@end smallexample
@end defun
@defun all-completions string collection &optional predicate
@defun all-completions string collection &optional predicate nospace
This function returns a list of all possible completions of
@var{string}. The parameters to this function are the same as to
@code{try-completion}.
@ -563,6 +563,9 @@ If @var{collection} is a function, it is called with three arguments:
@var{string}, @var{predicate} and @code{t}; then @code{all-completions}
returns whatever the function returns. @xref{Programmed Completion}.
If @var{nospace} is non-@code{nil}, completions that start with a space
are ignored unless @var{string} also starts with a space.
Here is an example, using the function @code{test} shown in the
example for @code{try-completion}:
@ -1369,12 +1372,17 @@ The current value of this variable is used to rebind @code{help-form}
locally inside the minibuffer (@pxref{Help Functions}).
@end defvar
@defun active-minibuffer-window
This function returns the currently active minibuffer window, or
@code{nil} if none is currently active.
@end defun
@defun minibuffer-window &optional frame
This function returns the window that is used for the minibuffer. In
Emacs 18, there is one and only one minibuffer window; this window
always exists and cannot be deleted. In Emacs 19, each frame can have
its own minibuffer, and this function returns the minibuffer window used
for frame @var{frame} (which defaults to the currently selected frame).
This function returns the minibuffer window used for frame @var{frame}.
If @var{frame} is @code{nil}, that stands for the current frame. Note
that the minibuffer window used by a frame need not be part of that
frame---a frame that has no minibuffer of its own necessarily uses some
other frame's minibuffer window.
@end defun
@c Emacs 19 feature

74
lispref/modes.texi
View file

@ -547,6 +547,16 @@ those such as Dired and Rmail that are useful only with text that has
been specially prepared.
@end defopt
@defun set-buffer-major-mode buffer
This function sets the major mode of @var{buffer} to the value of
@code{default-major-mode}. If that variable is @code{nil}, it uses
the current buffer's major mode (if that is suitable).
The low-level primitives for creating buffers do not use this function,
but medium-level commands such as @code{switch-to-buffer} should use it
whenever they create buffers.
@end defun
@defvar initial-major-mode
@cindex @samp{*scratch*}
The value of this variable determines the major mode of the initial
@ -929,7 +939,8 @@ Force redisplay of the current buffer's mode line.
strings, symbols, and numbers kept in the buffer-local variable
@code{mode-line-format}. The data structure is called a @dfn{mode line
construct}, and it is built in recursive fashion out of simpler mode line
constructs.
constructs. The same data structure is used for constructing
frame titles (pxref{Frame Titles}).
@defvar mode-line-format
The value of this variable is a mode line construct with overall
@ -1177,20 +1188,39 @@ The current buffer name, obtained with the @code{buffer-name} function.
The visited file name, obtained with the @code{buffer-file-name}
function. @xref{Buffer File Name}.
@item %F
The name of the selected frame.
@item %c
The current column number of point.
@item %l
The current line number of point.
@item %*
@samp{%} if the buffer is read only (see @code{buffer-read-only}); @*
@samp{*} if the buffer is modified (see @code{buffer-modified-p}); @*
@samp{-} otherwise. @xref{Buffer Modification}.
@item %+
@samp{*} if the buffer is modified (see @code{buffer-modified-p}); @*
@samp{%} if the buffer is read only (see @code{buffer-read-only}); @*
@samp{-} otherwise. This differs from @samp{%*} only for a modified
read-only buffer. @xref{Buffer Modification}.
@item %&
@samp{*} if the buffer is modified, and @samp{-} otherwise.
@item %s
The status of the subprocess belonging to the current buffer, obtained with
@code{process-status}. @xref{Process Information}.
@item %t
Whether the visited file is a text file or a binary file. (This is a
meaningful distinction only on certain operating systems.)
@item %p
The percent of the buffer above the @strong{top} of window, or
The percentage of the buffer text above the @strong{top} of window, or
@samp{Top}, @samp{Bottom} or @samp{All}.
@item %P
@ -1353,7 +1383,7 @@ For example, here's how @code{emacs-lisp-hooks} runs its mode hook:
@end example
@end defun
@defun add-hook hook function &optional append
@defun add-hook hook function &optional append local
This function is the handy way to add function @var{function} to hook
variable @var{hook}. The argument @var{function} may be any valid Lisp
function with the proper number of arguments. For example,
@ -1376,27 +1406,29 @@ executed first (barring another @code{add-hook} call).
If the optional argument @var{append} is non-@code{nil}, the new hook
function goes at the end of the hook list and will be executed last.
If @var{local} is non-@code{nil}, that says to make the new hook
function local to the current buffer. Before you can do this, you must
make the hook itself buffer-local by calling @code{make-local-hook}
(@strong{not} @code{make-local-variable}). If the hook itself is not
buffer-local, then the value of @var{local} makes no difference---the
hook function is always global.
@end defun
@defun remove-hook hook function
@defun remove-hook hook function &optional local
This function removes @var{function} from the hook variable @var{hook}.
If @var{local} is non-@code{nil}, that says to remove @var{function}
from the local hook list instead of from the global hook list. If the
hook itself is not buffer-local, then the value of @var{local} makes no
difference.
@end defun
@ignore @c Should no longer be necessary
If you make a hook variable buffer-local, copy its value before you use
@code{add-hook} or @code{remove-hook} to change it. For example,
@defun make-local-hook hook
This function makes the hook variable @code{hook} local to the current
buffer. When a hook variable is local, it can have local and global
hook functions, and @code{run-hooks} runs all of them.
@example
(defun my-major-mode ()
@dots{}
(make-local-variable 'foo-hook)
(if (boundp 'foo-hook)
(setq foo-hook (copy-sequence foo-hook)))
(add-hook 'foo-hook 'my-foo-function)"
@dots{}
)
@end example
Otherwise you may accidentally alter the list structure that forms part
of the global value of the hook variable.
@end ignore
Do not use @code{make-local-variable} directly for hook variables; it is
not sufficient.
@end defun

23
lispref/numbers.texi
View file

@ -372,8 +372,8 @@ commonly used.
if any argument is floating.
It is important to note that in GNU Emacs Lisp, arithmetic functions
do not check for overflow. Thus @code{(1+ 8388607)} may evaluate to
@minus{}8388608, depending on your hardware.
do not check for overflow. Thus @code{(1+ 134217727)} may evaluate to
@minus{}134217728, depending on your hardware.
@defun 1+ number-or-marker
This function returns @var{number-or-marker} plus 1.
@ -642,11 +642,11 @@ number.
The function @code{lsh}, like all Emacs Lisp arithmetic functions, does
not check for overflow, so shifting left can discard significant bits
and change the sign of the number. For example, left shifting 8,388,607
produces @minus{}2 on a 24-bit machine:
and change the sign of the number. For example, left shifting
134,217,727 produces @minus{}2 on a 28-bit machine:
@example
(lsh 8388607 1) ; @r{left shift}
(lsh 134217727 1) ; @r{left shift}
@result{} -2
@end example
@ -1009,8 +1009,17 @@ This function returns a pseudo-random integer. Repeated calls return a
series of pseudo-random integers.
If @var{limit} is @code{nil}, then the value may in principle be any
integer. If @var{limit} is a positive integer, the value is chosen to
be nonnegative and less than @var{limit} (only in Emacs 19).
integer. However, on machines where integers have more than 32 bits,
the possible values may be limited to the interval
@tex
$[0,2^{32})$.
@end tex
@ifinfo
[0,2**32).
@end ifinfo
If @var{limit} is a positive integer, the value is chosen to be
nonnegative and less than @var{limit} (only in Emacs 19).
If @var{limit} is @code{t}, it means to choose a new seed based on the
current time of day and on Emacs's process @sc{id} number.

63
lispref/objects.texi
View file

@ -1229,11 +1229,34 @@ pass an argument to @code{+} that it cannot handle:
@cindex type predicates
@cindex testing types
Lisp provides functions, called @dfn{type predicates}, to test whether
an object is a member of a given type. (Following a convention of long
standing, the names of most Emacs Lisp predicates end in @samp{p}.)
If you want your program to handle different types differently, you
must do explicit type checking. The most common way to check the type
of an object is to call a @dfn{type predicate} function. Emacs has a
type predicate for each type, as well as some predicates for
combinations of types.
Here is a table of predefined type predicates, in alphabetical order,
A type predicate function takes one argument; it returns @code{t} if
the argument belongs to the appropriate type, and @code{nil} otherwise.
Following a general Lisp convention for predicate functions, most type
predicates' names end with @samp{p}.
Here is an example which uses the predicates @code{listp} to check for
a list and @code{symbolp} to check for a symbol.
@example
(defun add-on (x)
(cond ((symbolp x)
;; If X is a symbol, put it on LIST.
(setq list (cons x list)))
((listp x)
;; If X is a list, add its elements to LIST.
(setq list (append x list)))
(t
;; We only handle symbols and lists.
(error "Invalid argument %s in add-on" x))))
@end example
Here is a table of predefined type predicates, in alphabetical order,
with references to further information.
@table @code
@ -1334,6 +1357,33 @@ with references to further information.
@xref{Basic Windows, windowp}.
@end table
The most general way to check the type of an object is to call the
function @code{type-of}. Recall that each object belongs to one and
only one primitive type; @code{type-of} tells you which one (@pxref{Lisp
Data Types}). But @code{type-of} knows nothing about non-primitive
types. In most cases, it is more convenient to use type predicates than
@code{type-of}.
@defun type-of object
This function returns a symbol naming the primitive type of
@var{object}. The value is one of @code{symbol}, @code{integer},
@code{float}, @code{string}, @code{cons}, @code{vector}, @code{marker},
@code{overlay}, @code{window}, @code{buffer}, @code{subr},
@code{compiled-function}, @code{window-configuration}, or
@code{process}.
@example
(type-of 1)
@result{} integer
(type-of 'nil)
@result{} symbol
(type-of '()) ; @r{@code{()} is @code{nil}.}
@result{} symbol
(type-of '(x))
@result{} cons
@end example
@end defun
@node Equality Predicates
@section Equality Predicates
@cindex equality
@ -1460,7 +1510,10 @@ arguments to see if their elements are the same. So, if two objects are
@end group
@end example
Comparison of strings uses @code{string=}, and is case-sensitive.
Comparison of strings is case-sensitive and takes account of text
properties as well as the characters in the strings. To compare
two strings' characters without comparing their text properties,
use @code{string=} (@pxref{Text Comparison}).
@example
@group

216
lispref/os.texi
View file

@ -20,6 +20,8 @@ pertaining to the terminal and the screen.
* System Environment:: Distinguish the name and kind of system.
* User Identification:: Finding the name and user id of the user.
* 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).
* Timers:: Setting a timer to call a function at a certain time.
* Terminal Input:: Recording terminal input for debugging.
* Terminal Output:: Recording terminal output for debugging.
@ -598,6 +600,23 @@ This function returns the name of the machine you are running on.
@end example
@end defun
@vindex system-name
The symbol @code{system-name} is a variable as well as a function. In
fact, the function returns whatever value the variable
@code{system-name} currently holds. Thus, you can set the variable
@code{system-name} in case Emacs is confused about the name of your
system. The variable is also useful for constructing frame titles
(@pxref{Frame Titles}).
@defvar mail-host-address
If this variable is non-@code{nil}, it is used instead of
@code{system-name} for purposes of generating email addresses. For
example, it is used when constructing the default value of
@code{user-mail-address}. @xref{User Identification}. (Since this is
done when Emacs starts up, the value actually used is the one saved when
Emacs was dumped. @xref{Building Emacs}.)
@end defvar
@defun getenv var
@cindex environment variable access
This function returns the value of the environment variable @var{var},
@ -631,6 +650,13 @@ function works by modifying @code{process-environment}; binding that
variable with @code{let} is also reasonable practice.
@end deffn
@defvar path-separator
This variable holds a string which says which character separates
directories in a search path (as found in an environment variable). Its
value is @code{":"} for Unix and GNU systems, and @code{";"} for MS-DOS
and Windows NT.
@end defvar
@defvar process-environment
This variable is a list of strings, each describing one environment
variable. The functions @code{getenv} and @code{setenv} work by means
@ -708,12 +734,21 @@ indicating whether the privilege is currently enabled.
@node User Identification
@section User Identification
@defun user-login-name
This function returns the name under which the user is logged in. If
the environment variable @code{LOGNAME} is set, that value is used.
Otherwise, if the environment variable @code{USER} is set, that value is
used. Otherwise, the value is based on the effective @sc{uid}, not the
real @sc{uid}.
@defvar user-mail-address
This holds the nominal email address of the user who is using Emacs.
When Emacs starts up, it computes a default value that is usually right,
but users often set this themselves when the default value is not right.
@end defvar
@defun user-login-name &optional uid
If you don't specify @var{uid}, this function returns the name under
which the user is logged in. If the environment variable @code{LOGNAME}
is set, that value is used. Otherwise, if the environment variable
@code{USER} is set, that value is used. Otherwise, the value is based
on the effective @sc{uid}, not the real @sc{uid}.
If you specify @var{uid}, the value is the user name that corresponds
to @var{uid} (which should be an integer).
@example
@group
@ -740,6 +775,28 @@ This function returns the full name of the user.
@end example
@end defun
@vindex user-full-name
@vindex user-real-login-name
@vindex user-login-name
The symbols @code{user-login-name}, @code{user-real-login-name} and
@code{user-full-name} are variables as well as functions. The functions
return the same values that the variables hold. These variables allow
you to ``fake out'' Emacs by telling the functions what to return. The
variables are also useful for constructing frame titles (@pxref{Frame
Titles}).
@defvar user-real-login-name
This variable holds the same value that the function
@code{user-real-login-name} returns. The variable lets you alter the value;
also, you can use variables for constructing frame titles.
@end defvar
@defvar user-full-name
This variable holds the same value that the function
@code{user-full-name} returns. The variable lets you alter the value;
also, you can use variables for constructing frame titles.
@end defvar
@defun user-real-uid
This function returns the real @sc{uid} of the user.
@ -825,7 +882,149 @@ The argument @var{time-value}, if given, specifies a time to analyze
instead of the current time. The argument should be a cons cell
containing two integers, or a list whose first two elements are
integers. Thus, you can use times obtained from @code{current-time}
(see below) and from @code{file-attributes} (@pxref{File Attributes}).
(see above) and from @code{file-attributes} (@pxref{File Attributes}).
@end defun
@node Time Conversion
@section Time Conversion
These functions convert time values (lists of two or three integers)
to strings or to calendrical information. There is also a function to
convert calendrical information to a time value. You can get time
values from the functions @code{current-time} (@pxref{Time of Day}) and
@code{file-attributes} (@pxref{File Attributes}).
@defun format-time-string format-string time
This function converts @var{time} to a string according to
@var{format-string}. The argument @var{format-string} may contain
@samp{%}-sequences which say to substitute parts of the time. Here is a
table of what the @samp{%}-sequences mean:
@table @samp
@item %a
This stands for the abbreviated name of the day of week.
@item %A
This stands for the full name of the day of week.
@item %b
This stands for the abbreviated name of the month.
@item %B
This stands for the full name of the month.
@item %c
This is a synonym for @samp{%x %X}.
@item %C
This has a locale-specific meaning. In the C locale, it is equivalent
to @samp{%A, %B %e, %Y}.
@item %d
This stands for the day of month, zero-padded.
@item %D
This is a synonym for @samp{%m/%d/%y}.
@item %e
This stands for the day of month, blank-padded.
@item %h
This is a synonym for @samp{%b}.
@item %H
This stands for the hour (00-23).
@item %I
This stands for the hour (00-12).
@item %j
This stands for the day of the year (001-366).
@item %k
This stands for the hour (0-23), blank padded.
@item %l
This stands for the hour (1-12), blank padded.
@item %m
This stands for the month (01-12).
@item %M
This stands for the minute (00-59).
@item %n
This stands for a newline.
@item %p
This stands for @samp{AM} or @samp{PM}, as appropriate.
@item %r
This is a synonym for @samp{%I:%M:%S %p}.
@item %R
This is a synonym for @samp{%H:%M}.
@item %S
This stands for the seconds (00-60).
@item %t
This stands for a tab character.
@item %T
This is a synonym for @samp{%H:%M:%S}.
@item %U
This stands for the week of the year (01-52), assuming that weeks
start on Sunday.
@item %w
This stands for the numeric day of week (0-6). Sunday is day 0.
@item %W
This stands for the week of the year (01-52), assuming that weeks
start on Monday.
@item %x
This has a locale-specific meaning. In the C locale, it is equivalent
to @samp{%D}.
@item %X
This has a locale-specific meaning. In the C locale, it is equivalent
to @samp{%T}.
@item %y
This stands for the year without century (00-99).
@item %Y
This stands for the year with century.
@item %Z
This stands for the time zone abbreviation.
@end table
@end defun
@defun decode-time time
This function converts a time value into calendrical form. The return
value is a list of nine elements, as follows:
@example
(@var{seconds} @var{minutes} @var{hour} @var{day} @var{month} @var{year} @var{dow} @var{dst} @var{zone})
@end example
Here is what the elements mean:
@table @var
@item sec
The number of seconds past the minute, as an integer between 0 and 59.
@item minute
The number of minutes past the hour, as an integer between 0 and 59.
@item hour
The hour of the day, as an integer between 0 and 23.
@item day
The day of the month, as an integer between 1 and 31.
@item month
The month of the year, as an integer between 1 and 12.
@item year
The year, an integer typically greater than 1900.
@item dow
The day of week, as an integer between 0 and 6, where 0 stands for
Sunday.
@item dst
@code{t} if daylight savings time is effect, otherwise @code{nil}.
@item zone
An integer indicating the number of seconds east of Greenwich.
@end table
Note that Common Lisp has different meanings for @var{dow} and
@var{zone}.
@end defun
@defun encode-time seconds minutes hour day month year &optional zone
This function is the inverse of @code{decode-time}. It converts seven
items of calendrical data into a time value.
For the meanings of the arguments, see the table above under
@code{decode-time}.
Year numbers less than 100 are treated just like other year numbers. If
you them to stand for years above 1900, you must alter them yourself
before you call @code{encode-time}.
The optional argument @var{zone} defaults to the current time zone and
its daylight savings time rules. If specified, it can be either a list
(as you would get from @code{current-time-zone}) or an integer (as you
would get from @code{decode-time}). The specified zone is used without
any further alteration for daylight savings time.
@end defun
@node Timers
@ -1271,6 +1470,9 @@ by HP X servers whose numeric code is (1 << 28) + 168.
It is not a problem if the alist defines keysyms for other X servers, 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
buffer-local. @xref{Multiple Displays}.
@end defvar
@node Flow Control

86
lispref/processes.texi
View file

@ -148,23 +148,52 @@ user types another @kbd{C-g}, that kills the subprocess instantly with
18. In version 19, they return an indication of how the process
terminated.
@defun call-process program &optional infile buffer-or-name display &rest args
@defun call-process program &optional infile destination display &rest args
This function calls @var{program} in a separate process and waits for
it to finish.
The standard input for the process comes from file @var{infile} if
@var{infile} is not @code{nil} and from @file{/dev/null} otherwise. The
process output gets inserted in buffer @var{buffer-or-name} before point,
if that argument names a buffer. If @var{buffer-or-name} is @code{t},
output is sent to the current buffer; if @var{buffer-or-name} is
@code{nil}, output is discarded.
@var{infile} is not @code{nil} and from @file{/dev/null} otherwise.
The argument @var{destination} says where to put the process output.
Here are the possibilities:
If @var{buffer-or-name} is the integer 0, @code{call-process} returns
@code{nil} immediately and discards any output. In this case, the
process is not truly synchronous, since it can run in 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.
@table @asis
@item a buffer
Insert the output in that buffer, before point. This includes both the
standard output stream and the standard error stream of the process.
@item a string
Find or create a buffer with that name, then insert
the output in that buffer, before point.
@item @code{t}
Insert the output in the current buffer, before point.
@item @code{nil}
Discard the output.
@item 0
Discard the output, and return immediately without waiting
for the subprocess to finish.
In this case, the process is not truly synchronous, since it can run in
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})
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}.
The value @code{nil} means discard it, @code{t} means mix it with the
ordinary output, and a string specifies a file name to redirect error
output into.
You can't directly specify a buffer to put the error output in; that is
too difficult to implement. But you can achieve this result by sending
the error output to a temporary file and then inserting the file into a
buffer.
@end table
If @var{display} is non-@code{nil}, then @code{call-process} redisplays
the buffer as output is inserted. Otherwise the function does no
@ -216,16 +245,16 @@ of @code{call-process}:
@end smallexample
@end defun
@defun call-process-region start end program &optional delete buffer-or-name display &rest args
@defun call-process-region start end program &optional delete destination display &rest args
This function sends the text between @var{start} to @var{end} as
standard input to a process running @var{program}. It deletes the text
sent if @var{delete} is non-@code{nil}; this is useful when @var{buffer}
is @code{t}, to insert the output in the current buffer.
The arguments @var{buffer-or-name} and @var{display} control what to do
The arguments @var{destination} and @var{display} control what to do
with the output from the subprocess, and whether to update the display
as it comes in. For details, see the description of
@code{call-process}, above. If @var{buffer-or-name} is the integer 0,
@code{call-process}, above. If @var{destination} is the integer 0,
@code{call-process-region} discards the output and returns @code{nil}
immediately, without waiting for the subprocess to finish.
@ -241,7 +270,7 @@ In the following example, we use @code{call-process-region} to run the
@code{cat} utility, with standard input being the first five characters
in buffer @samp{foo} (the word @samp{input}). @code{cat} copies its
standard input into its standard output. Since the argument
@var{buffer-or-name} is @code{t}, this output is inserted in the current
@var{destination} is @code{t}, this output is inserted in the current
buffer.
@smallexample
@ -390,6 +419,10 @@ with one subprocess by binding the variable around the call to
(start-process @dots{}))
@end group
@end smallexample
To determine whether a given subprocess actually got a pipe or a
@sc{pty}, use the function @code{process-tty-name} (@pxref{Process
Information}).
@end defvar
@node Deleting Processes
@ -560,6 +593,13 @@ determine which of those it is.) If @var{process} has not yet
terminated, the value is 0.
@end defun
@defun process-tty-name process
This function returns the terminal name that @var{process} is using for
its communication with Emacs---or @code{nil} if it is using pipes
instead of a terminal (see @code{process-connection-type} in
@ref{Asynchronous Processes}).
@end defun
@node Input to Processes
@section Sending Input to Processes
@cindex process input
@ -846,6 +886,13 @@ command would be unpredictable. If you want to permit quitting inside a
filter function, bind @code{inhibit-quit} to @code{nil}.
@xref{Quitting}.
If an error happens during execution of a filter function, it is
caught automatically, so that it doesn't stop the execution of whatever
programs was running when the filter function was started. However, if
@code{debug-on-error} is non-@code{nil}, the error-catching is turned
off. This makes it possible to use the Lisp debugger to debug the
filter function. @xref{Debugger}.
Many filter functions sometimes or always insert the text in the
process's buffer, mimicking the actions of Emacs when there is no
filter. Such filter functions need to use @code{set-buffer} in order to
@ -1057,6 +1104,13 @@ matching had to explicitly save and restore the match data. Now Emacs
does this automatically; sentinels never need to do it explicitly.
@xref{Match Data}.
If an error happens during execution of a sentinel, it is caught
automatically, so that it doesn't stop the execution of whatever
programs was running when the sentinel was started. However, if
@code{debug-on-error} is non-@code{nil}, the error-catching is turned
off. This makes it possible to use the Lisp debugger to debug the
sentinel. @xref{Debugger}.
@defun set-process-sentinel process sentinel
This function associates @var{sentinel} with @var{process}. If
@var{sentinel} is @code{nil}, then the process will have no sentinel.

155
lispref/searching.texi
View file

@ -17,6 +17,7 @@ portions of it.
* String Search:: Search for an exact match.
* Regular Expressions:: Describing classes of strings.
* Regexp Search:: Searching for a match for a regexp.
* POSIX Regexps:: Searching POSIX-style for the longest match.
* Search and Replace:: Internals of @code{query-replace}.
* Match Data:: Finding out which part of the text matched
various parts of a regexp, after regexp search.
@ -226,12 +227,12 @@ The next alternative is for @samp{a*} to match only two @samp{a}s.
With this choice, the rest of the regexp matches successfully.@refill
Nested repetition operators can be extremely slow if they specify
backtracking loops. For example, @samp{\(x+y*\)*a} could take hours to
match the sequence @samp{xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxz}. The
slowness is because Emacs must try each imaginable way of grouping the
35 @samp{x}'s before concluding that none of them can work. To make
sure your regular expressions run fast, check nested repetitions
carefully.
backtracking loops. For example, it could take hours for the regular
expression @samp{\(x+y*\)*a} to match the sequence
@samp{xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxz}. The slowness is because
Emacs must try each imaginable way of grouping the 35 @samp{x}'s before
concluding that none of them can work. To make sure your regular
expressions run fast, check nested repetitions carefully.
@item +
@cindex @samp{+} in regexp
@ -715,6 +716,48 @@ comes back" twice.
@end example
@end defun
@node POSIX Regexps
@section POSIX Regular Expression Searching
The usual regular expression functions do backtracking when necessary
to handle the @samp{\|} and repetition constructs, but they continue
this only until they find @emph{some} match. Then they succeed and
report the first match found.
This section describes alternative search functions which perform the
full backtracking specified by the POSIX standard for regular expression
matching. They continue backtracking until they have tried all
possibilities and found all matches, so they can report the longest
match, as required by POSIX. This is much slower, so use these
functions only when you really need the longest match.
In Emacs versions prior to 19.29, these functions did not exist, and
the functions described above implemented full POSIX backtracking.
@defun posix-search-forward regexp &optional limit noerror repeat
This is like @code{re-search-forward} except that it performs the full
backtracking specified by the POSIX standard for regular expression
matching.
@end defun
@defun posix-search-backward regexp &optional limit noerror repeat
This is like @code{re-search-backward} except that it performs the full
backtracking specified by the POSIX standard for regular expression
matching.
@end defun
@defun posix-looking-at regexp
This is like @code{looking-at} except that it performs the full
backtracking specified by the POSIX standard for regular expression
matching.
@end defun
@defun posix-string-match regexp string &optional start
This is like @code{string-match} except that it performs the full
backtracking specified by the POSIX standard for regular expression
matching.
@end defun
@ignore
@deffn Command delete-matching-lines regexp
This function is identical to @code{delete-non-matching-lines}, save
@ -909,34 +952,56 @@ match data around it, to prevent it from being overwritten.
@node Simple Match Data
@subsection Simple Match Data Access
This section explains how to use the match data to find the starting
point or ending point of the text that was matched by a particular
search, or by a particular parenthetical subexpression of a regular
expression.
This section explains how to use the match data to find out what was
matched by the last search or match operation.
You can ask about the entire matching text, or about a particular
parenthetical subexpression of a regular expression. The @var{count}
argument in the functions below specifies which. If @var{count} is
zero, you are asking about the entire match. If @var{count} is
positive, it specifies which subexpression you want.
Recall that the subexpressions of a regular expression are those
expressions grouped with escaped parentheses, @samp{\(@dots{}\)}. The
@var{count}th subexpression is found by counting occurrences of
@samp{\(} from the beginning of the whole regular expression. The first
subexpression is numbered 1, the second 2, and so on. Only regular
expressions can have subexpressions---after a simple string search, the
only information available is about the entire match.
@defun match-string count &optional in-string
This function returns, as a string, the text matched in the last search
or match operation. It returns the entire text if @var{count} is zero,
or just the portion corresponding to the @var{count}th parenthetical
subexpression, if @var{count} is positive. If @var{count} is out of
range, the value is @code{nil}.
If the last such operation was done against a string with
@code{string-match}, then you should pass the same string as the
argument @var{in-string}. Otherwise, after a buffer search or match,
you should omit @var{in-string} or pass @code{nil} for it; but you
should make sure that the current buffer when you call
@code{match-string} is the one in which you did the searching or
matching.
@end defun
@defun match-beginning count
This function returns the position of the start of text matched by the
last regular expression searched for, or a subexpression of it.
If @var{count} is zero, then the value is the position of the start of
the text matched by the whole regexp. Otherwise, @var{count}, specifies
a subexpression in the regular expresion. The value of the function is
the starting position of the match for that subexpression.
the entire match. Otherwise, @var{count}, specifies a subexpression in
the regular expresion, and the value of the function is the starting
position of the match for that subexpression.
Subexpressions of a regular expression are those expressions grouped
with escaped parentheses, @samp{\(@dots{}\)}. The @var{count}th
subexpression is found by counting occurrences of @samp{\(} from the
beginning of the whole regular expression. The first subexpression is
numbered 1, the second 2, and so on.
The value is @code{nil} for a subexpression inside a
@samp{\|} alternative that wasn't used in the match.
The value is @code{nil} for a subexpression inside a @samp{\|}
alternative that wasn't used in the match.
@end defun
@defun match-end count
This function returns the position of the end of the text that matched
the last regular expression searched for, or a subexpression of it.
This function is otherwise similar to @code{match-beginning}.
This function is like @code{match-beginning} except that it returns the
position of the end of the match, rather than the position of the
beginning.
@end defun
Here is an example of using the match data, with a comment showing the
@ -950,6 +1015,15 @@ positions within the text:
@result{} 4
@end group
@group
(match-string 0 "The quick fox jumped quickly.")
@result{} "quick"
(match-string 1 "The quick fox jumped quickly.")
@result{} "qu"
(match-string 2 "The quick fox jumped quickly.")
@result{} "ick"
@end group
@group
(match-beginning 1) ; @r{The beginning of the match}
@result{} 4 ; @r{with @samp{qu} is at index 4.}
@ -1004,11 +1078,15 @@ character of the buffer counts as 1.)
@var{replacement}.
@cindex case in replacements
@defun replace-match replacement &optional fixedcase literal
This function replaces the buffer text matched by the last search, with
@var{replacement}. It applies only to buffers; you can't use
@code{replace-match} to replace a substring found with
@code{string-match}.
@defun replace-match replacement &optional fixedcase literal string
This function replaces the text in the buffer (or in @var{string}) that
was matched by the last search. It replaces that text with
@var{replacement}.
If @var{string} is @code{nil}, @code{replace-match} does the replacement
by editing the buffer; it leaves point at the end of the replacement
text, and returns @code{t}. If @var{string} is a string, it does the
replacement by constructing and returning a new string.
If @var{fixedcase} is non-@code{nil}, then the case of the replacement
text is not changed; otherwise, the replacement text is converted to a
@ -1044,9 +1122,6 @@ Subexpressions are those expressions grouped inside @samp{\(@dots{}\)}.
@cindex @samp{\} in replacement
@samp{\\} stands for a single @samp{\} in the replacement text.
@end table
@code{replace-match} leaves point at the end of the replacement text,
and returns @code{t}.
@end defun
@node Entire Match Data
@ -1239,19 +1314,27 @@ default value is @code{"^\014"} (i.e., @code{"^^L"} or @code{"^\C-l"});
this matches a line that starts with a formfeed character.
@end defvar
The following two regular expressions should @emph{not} assume the
match always starts at the beginning of a line; they should not use
@samp{^} to anchor the match. Most often, the paragraph commands do
check for a match only at the beginning of a line, which means that
@samp{^} would be superfluous. When there is a left margin, they accept
matches that start after the left margin. In that case, a @samp{^}
would be incorrect.
@defvar paragraph-separate
This is the regular expression for recognizing the beginning of a line
that separates paragraphs. (If you change this, you may have to
change @code{paragraph-start} also.) The default value is
@w{@code{"^[@ \t\f]*$"}}, which matches a line that consists entirely of
spaces, tabs, and form feeds.
@w{@code{"[@ \t\f]*$"}}, which matches a line that consists entirely of
spaces, tabs, and form feeds (after its left margin).
@end defvar
@defvar paragraph-start
This is the regular expression for recognizing the beginning of a line
that starts @emph{or} separates paragraphs. The default value is
@w{@code{"^[@ \t\n\f]"}}, which matches a line starting with a space, tab,
newline, or form feed.
@w{@code{"[@ \t\n\f]"}}, which matches a line starting with a space, tab,
newline, or form feed (after its left margin).
@end defvar
@defvar sentence-end

11
lispref/sequences.texi
View file

@ -462,11 +462,12 @@ existing vector.
@end group
@end example
When an argument is an integer (not a sequence of integers), it is
converted to a string of digits making up the decimal printed
representation of the integer. This special case exists for
compatibility with Mocklisp, and we don't recommend you take advantage
of it. If you want to convert an integer to digits in this way, use
The @code{vconcat} function also allows integers as arguments. It
converts them to strings of digits, making up the decimal print
representation of the integer, and then uses the strings instead of the
original integers. @strong{Don't use this feature; we plan to eliminate
it. If you already use this feature, change your programs now!} The
proper way to convert an integer to a decimal number in this way is with
@code{format} (@pxref{Formatting Strings}) or @code{number-to-string}
(@pxref{String Conversion}).

12
lispref/strings.texi
View file

@ -218,10 +218,10 @@ not @code{eq} to any existing string.
When an argument is an integer (not a sequence of integers), it is
converted to a string of digits making up the decimal printed
representation of the integer. @string{Don't use this feature---it
exists for historical compatibility only, and we plan to change it by
and by.} If you wish to convert an integer to a decimal number in this
way, use @code{format} (@pxref{Formatting Strings}) or
representation of the integer. @strong{Don't use this feature; we plan
to eliminate it. If you already use this feature, change your programs
now!} The proper way to convert an integer to a decimal number in this
way is with @code{format} (@pxref{Formatting Strings}) or
@code{number-to-string} (@pxref{String Conversion}).
@example
@ -270,6 +270,10 @@ match exactly; case is significant.
(string= "ab" "ABC")
@result{} nil
@end example
The function @code{string=} ignores the text properties of the
two strings. To compare strings in a way that compares their text
properties also, use @code{equal} (@pxref{Equality Predicates}).
@end defun
@defun string-equal string1 string2

63
lispref/symbols.texi
View file

@ -350,6 +350,20 @@ See @code{documentation} in @ref{Accessing Documentation}, for another
example using @code{mapatoms}.
@end defun
@defun unintern symbol &optional obarray
This function deletes @var{symbol} from the obarray @var{obarray}. If
@code{symbol} is not actually in the obarray, @code{unintern} does
nothing. If @var{obarray} is @code{nil}, the current obarray is used.
If you provide a string instead of a symbol as @var{symbol}, it stands
for a symbol name. Then @code{unintern} deletes the symbol (if any) in
the obarray which has that name. If there is no such symbol,
@code{unintern} does nothing.
If @code{unintern} does delete a symbol, it returns @code{t}. Otherwise
it returns @code{nil}.
@end defun
@node Property Lists,, Creating Symbols, Symbols
@section Property Lists
@cindex property list
@ -379,6 +393,16 @@ objects, but the names are usually symbols. They are compared using
Here @code{lisp-indent-function} and @code{byte-compile} are property
names, and the other two elements are the corresponding values.
@menu
* Plists and Alists:: Comparison of the advantages of property
lists and association lists.
* Symbol Plists:: Functions to access symbols' property lists.
* Other Plists:: Accessing property lists stored elsewhere.
@end menu
@node Plists and Alists
@subsection Property Lists and Association Lists
@cindex property lists vs association lists
Association lists (@pxref{Association Lists}) are very similar to
property lists. In contrast to association lists, the order of the
@ -408,12 +432,15 @@ name.) An association list may be used like a stack where associations
are pushed on the front of the list and later discarded; this is not
possible with a property list.
@node Symbol Plists
@subsection Property List Functions for Symbols
@defun symbol-plist symbol
This function returns the property list of @var{symbol}.
@end defun
@defun setplist symbol plist
This function sets @var{symbol}'s property list to @var{plist}.
This function sets @var{symbol}'s property list to @var{plist}.
Normally, @var{plist} should be a well-formed property list, but this is
not enforced.
@ -458,3 +485,37 @@ The @code{put} function returns @var{value}.
@result{} (verb transitive noun (a buzzing little bug))
@end smallexample
@end defun
@node Other Plists
@subsection Property Lists Outside Symbols
These two functions are useful for manipulating property lists
that are stored in places other than symbols:
@defun plist-get plist property
This returns the value of the @var{property} property
stored in the property list @var{plist}. For example,
@example
(plist-get '(foo 4) 'foo)
@result{} 4
@end example
@end defun
@defun plist-put plist property value
This stores @var{value} as the value of the @var{property} property
stored in the property list @var{plist}. It may modify @var{plist}
destructively, or it may construct new list structure without altering
the old. The function returns the modified property list, so you can
store that back in the place where you got @var{plist}. For example,
@example
(setq my-plist '(bar t foo 4))
@result{} (bar t foo 4)
(setq my-plist (plist-put my-plist 'foo 69))
@result{} (bar t foo 69)
(setq my-plist (plist-put my-plist 'quux '(a)))
@result{} (quux (a) bar t foo 5)
@end example
@end defun

222
lispref/text.texi
View file

@ -156,6 +156,11 @@ It is not necessary for @var{start} to be less than @var{end}; the
arguments can be given in either order. But most often the smaller
argument is written first.
If the text being copied has any text properties, these are copied into
the string along with the characters they belong to. @xref{Text
Properties}. However, overlays (@pxref{Overlays}) in the buffer and
their properties are ignored, not copied.
@example
@group
---------- Buffer: foo ----------
@ -176,6 +181,24 @@ This is the contents of buffer foo
@end example
@end defun
@defun buffer-substring-without-properties start end
This is like @code{buffer-substring}, except that it does not copy text
properties, just the characters themselves. @xref{Text Properties}.
Here's an example of using this function to get a word to look up in an
alist:
@example
(setq flammable
(assoc (buffer-substring start end)
'(("wood" . t) ("paper" . t)
("steel" . nil) ("asbestos" . nil))))
@end example
If this were written using @code{buffer-substring} instead, it would not
work reliably; any text properties that happened to be in the word
copied from the buffer would make the comparisons fail.
@end defun
@defun buffer-string
This function returns the contents of the accessible portion of the
current buffer as a string. This is the portion between
@ -343,18 +366,17 @@ it except to install it on a keymap.
In an interactive call, @var{count} is the numeric prefix argument.
This function calls @code{auto-fill-function} if the current column number
is greater than the value of @code{fill-column} and the character
inserted is a space (@pxref{Auto Filling}).
This command calls @code{auto-fill-function} whenever that is
non-@code{nil} and the character inserted is a space or a newline
(@pxref{Auto Filling}).
@c Cross refs reworded to prevent overfull hbox. --rjc 15mar92
This function performs abbrev expansion if Abbrev mode is enabled and
This command performs abbrev expansion if Abbrev mode is enabled and
the inserted character does not have word-constituent
syntax. (@xref{Abbrevs}, and @ref{Syntax Class Table}.)
This function is also responsible for calling
@code{blink-paren-function} when the inserted character has close
parenthesis syntax (@pxref{Blinking}).
This is also responsible for calling @code{blink-paren-function} when
the inserted character has close parenthesis syntax (@pxref{Blinking}).
@end deffn
@deffn Command newline &optional number-of-newlines
@ -710,6 +732,9 @@ the kill ring, but does not delete the text from the buffer. It returns
@code{nil}. It also indicates the extent of the text copied by moving
the cursor momentarily, or by displaying a message in the echo area.
The command does not set @code{this-command} to @code{kill-region}, so a
subsequent kill command does not append to the same kill ring entry.
Don't call @code{copy-region-as-kill} in Lisp programs unless you aim to
support Emacs 18. For Emacs 19, it is better to use @code{kill-new} or
@code{kill-append} instead. @xref{Low-Level Kill Ring}.
@ -1073,8 +1098,11 @@ specified width. The width is controlled by the variable
automatically as you insert it, but changes to existing text may leave
it improperly filled. Then you must fill the text explicitly.
Most of the functions in this section return values that are not
meaningful.
Most of the commands in this section return values that are not
meaningful. All the functions that do filling take note of the current
left margin, current right margin, and current justification style. If
the current justification style is @code{none}, the filling functions
don't actually do anything.
@deffn Command fill-paragraph justify-flag
@cindex filling a paragraph
@ -1123,8 +1151,11 @@ described above.
This command considers a region of text as a paragraph and fills it. If
the region was made up of many paragraphs, the blank lines between
paragraphs are removed. This function justifies as well as filling when
@var{justify-flag} is non-@code{nil}. In an interactive call, any
prefix argument requests justification.
@var{justify-flag} is non-@code{nil}. The precise value of
@var{justify-flag} specifies a style of justification, as in
@code{justify-current-line}, below.
In an interactive call, any prefix argument requests justification.
In Adaptive Fill mode, which is enabled by default,
@code{fill-region-as-paragraph} on an indented paragraph when there is
@ -1132,12 +1163,38 @@ no fill prefix uses the indentation of the second line of the paragraph
as the fill prefix.
@end deffn
@deffn Command justify-current-line
@deffn Command justify-current-line how eop nosqueeze
This command inserts spaces between the words of the current line so
that the line ends exactly at @code{fill-column}. It returns
@code{nil}.
The argument @var{how}, if non-@code{nil} specifies explicitly the style
of justification. It can be @code{left}, @code{right}, @code{full},
@code{center}, or @code{none}. If it is @code{t}, that means to do
follow specified justification style (see @code{current-justification},
below). @code{nil} means to do full justification.
If @var{eop} is non-@code{nil}, that means do left-justification when
@code{current-justification} specifies full justification. This is used
for the last line of a paragraph; even if the paragraph as a whole is
fully justified, the last line should not be.
If @var{nosqueeze} is non-@code{nil}, that means do not change interior
whitespace.
@end deffn
@defopt default-justification
This variable's value specifies the style of justification to use for
text that doesn't specify a style with a text property. The possible
values are @code{left}, @code{right}, @code{full}, @code{center}, or
@code{none}.
@end defopt
@defun current-justification
This function returns the proper justification style to use for filling
the text around point.
@end defun
@defopt fill-prefix
This variable specifies a string of text that appears at the beginning
of normal text lines and should be disregarded when filling them. Any
@ -1168,6 +1225,67 @@ buffers that do not override it. This is the same as
The default value for @code{default-fill-column} is 70.
@end defvar
@defvar fill-paragraph-function
This variable provides a way for major modes to override the filling of
paragraphs. If the value is non-@code{nil}, @code{fill-paragraph} calls
this function to do the work. If the function returns a non-@code{nil}
value, @code{fill-paragraph} assumes the job is done, and immediately
returns that value.
The usual use of this feature is to fill comments in programming
language modes. If the function needs to fill a paragraph in the usual
way, it can do so as follows:
@example
(let ((fill-paragraph-function nil))
(fill-paragraph arg))
@end example
@end defvar
@deffn Command set-left-margin from to margin
This sets the @code{left-margin} property on the text from @var{from} to
@var{to} to the value @var{margin}. If Auto Fill mode is enabled, this
command also refills the region to fit the new margin.
@end deffn
@deffn Command set-right-margin from to margin
This sets the @code{fill-colmn} property on the text from @var{from} to
@var{to} so as to yield a right margin of width @var{margin}. If Auto
Fill mode is enabled, this command also refills the region to fit the
new margin.
@end deffn
@defun current-left-margin
This function returns the proper left margin value to use for filling
the text around point. The value is the sum of the @code{left-margin}
property of the character at the start of the current line (or zero if
none), plus the value of the variable @code{left-margin}.
@end defun
@defun current-fill-column
This function returns the proper fill column value to use for filling
the text around point. The value is the value of the @code{fill-column}
variable, minus the value of the @code{right-margin} property of the
character after point.
@end defun
@deffn Command move-to-left-margin &optional n force
This function moves point to the left margin of the current line. The
column moved to is determined by calling the function
@code{current-left-margin}. If the argument @var{n} is specified,
@code{move-to-left-margin} moves forward @var{n}@minus{}1 lines first.
If @var{force} is non-@code{nil}, that says to fix the line's
indentation if that doesn't match the left margin value.
@end deffn
@defun delete-to-left-margin from to
This function removes left margin indentation from the text
between @var{from} and @var{to}. The amount of indentation
to delete is determined by calling @code{current-left-margin}.
In no case does this function delete non-whitespace.
@end defun
@node Auto Filling
@comment node-name, next, previous, up
@section Auto Filling
@ -1180,10 +1298,9 @@ For a description of functions that you can call explicitly to fill and
justify existing text, see @ref{Filling}.
@defvar auto-fill-function
The value of this variable should be a function (of no arguments) to
be called after self-inserting a space at a column beyond
@code{fill-column}. It may be @code{nil}, in which case nothing
special is done.
The value of this variable should be a function (of no arguments) to be
called after self-inserting a space or a newline. It may be @code{nil},
in which case nothing special is done in that case.
The value of @code{auto-fill-function} is @code{do-auto-fill} when
Auto-Fill mode is enabled. That is a function whose sole purpose is to
@ -1935,6 +2052,7 @@ along with the characters; this includes such diverse functions as
* Changing Properties:: Setting the properties of a range of text.
* Property Search:: Searching for where a property changes value.
* Special Properties:: Particular properties with special meanings.
* Format Properties:: Properties for representing formatting of text.
* Sticky Properties:: How inserted text gets properties from
neighboring text.
* Saving Properties:: Saving text properties in files, and reading
@ -1986,6 +2104,22 @@ This function returns the entire property list of the character at
@code{nil}, it defaults to the current buffer.
@end defun
@defvar default-text-properties
This variable holds a property list giving default values for text
properties. Whenever a character does not specify a value for a
property, the value stored in this list is used instead. Here is an
example:
@example
(setq default-text-properties '(foo 69))
;; @r{Make sure character 1 has no properties of its own.}
(set-text-properties 1 2 nil)
;; @r{What we get, when we ask, is the default value.}
(get-text-property 1 'foo)
@result{} 69
@end example
@end defvar
@node Changing Properties
@subsection Changing Text Properties
@ -2068,6 +2202,10 @@ from the specified range of text. Here's an example:
@end example
@end defun
See also the function @code{buffer-substring-without-properties}
(@pxref{Buffer Contents}) which copies text from the buffer
but does not copy its properties.
@node Property Search
@subsection Property Search Functions
@ -2188,9 +2326,9 @@ of the symbol serve as defaults for the properties of the character.
@cindex face codes of text
@kindex face @r{(text property)}
You can use the property @code{face} to control the font and color of
text. @xref{Faces}, for more information. This feature is temporary;
in the future, we may replace it with other ways of specifying how to
display text.
text. Its value is a face name or a list of face names. @xref{Faces},
for more information. This feature may be temporary; in the future, we
may replace it with other ways of specifying how to display text.
@item mouse-face
@kindex mouse-face @r{(text property)}
@ -2225,16 +2363,19 @@ and then remove the property. @xref{Read Only Buffers}.
@item invisible
@kindex invisible @r{(text property)}
A non-@code{nil} @code{invisible} property means a character does not
appear on the screen. This works much like selective display. Details
of this feature are likely to change in future versions, so check the
@file{etc/NEWS} file in the version you are using.
A non-@code{nil} @code{invisible} property can make a character invisible
on the screen. @xref{Invisible Text}, for details.
@item intangible
@kindex intangible @r{(text property)}
A non-@code{nil} @code{intangible} property on a character prevents
putting point before that character. If you try, point actually goes
after the character (and after all succeeding intangible characters).
If a group of consecutive characters have equal and non-@code{nil}
@code{intangible} properties, then you cannot place point between them.
If you move point forward into the group, point actually moves to the
end of the group. If you try to move point backward into the group,
point actually moves to the start of the group.
When the variable @code{inhibit-point-motion-hooks} is non-@code{nil},
the @code{intangible} property is ignored.
@item modification-hooks
@cindex change hooks for a character
@ -2298,9 +2439,36 @@ value of point runs these hook functions.
@defvar inhibit-point-motion-hooks
When this variable is non-@code{nil}, @code{point-left} and
@code{point-entered} hooks are not run.
@code{point-entered} hooks are not run, and the @code{intangible}
property has no effect.
@end defvar
@node Format Properties
@section Formatted Text Properties
These text properties affect the behavior of the fill commands. They
are used for representing formatted text. @xref{Filling}.
@table code
@item hard
If a newline character has this property, it is a ``hard'' newline.
The fill commands do not alter hard newlines and do not move words
across them. However, this property takes effect only if the variable
@code{use-hard-newlines} is non-@code{nil}.
@item right-margin
This property specifies the right margin for filling this part of the
text.
@item left-margin
This property specifies the left margin for filling this part of the
text.
@item justification
This property specifies the style of justification for filling this part
of the text.
@end table
@node Sticky Properties
@subsection Stickiness of Text Properties
@cindex sticky text properties

46
lispref/variables.texi
View file

@ -708,6 +708,39 @@ always affects the most local existing binding.
@end quotation
@end defun
One other function for setting a variable is designed to add
an element to a list if it is not already present in the list.
@defun add-to-list symbol element
This function sets the variable @var{symbol} by consing @var{element}
onto the old value, if @var{element} is not already a member of that
value. The value of @var{symbol} had better be a list already.
Here's a scenario showing how to use @code{add-to-list}:
@example
(setq foo '(a b))
@result{} (a b)
(add-to-list 'foo 'c) ;; @r{Add @code{c}.}
@result{} (c a b)
(add-to-list 'foo 'b) ;; @r{No effect.}
@result{} (c a b)
foo ;; @r{@code{foo} was changed.}
@result{} (c a b)
@end example
@end defun
An equivalent expression for @code{(add-to-list '@var{var}
@var{value})} is this:
@example
(or (member @var{value} @var{var})
(setq @var{var} (cons @var{value} @var{var})))
@end example
@node Variable Scoping
@section Scoping Rules for Variable Bindings
@ -921,7 +954,8 @@ languages in one form or another. Emacs also supports another, unusual
kind of variable binding: @dfn{buffer-local} bindings, which apply only
to one buffer. Emacs Lisp is meant for programming editing commands,
and having different values for a variable in different buffers is an
important customization method.
important customization method. (A few variables have bindings that
are local to a given X terminal; see @ref{Multiple Displays}.)
@menu
* Intro to Buffer-Local:: Introduction and concepts.
@ -1072,6 +1106,9 @@ Making a variable buffer-local within a @code{let}-binding for that
variable does not work. This is because @code{let} does not distinguish
between different kinds of bindings; it knows only which variable the
binding was made for.
@strong{Note:} do not use @code{make-local-variable} for a hook
variable. Instead, use @code{make-local-hook}. @xref{Hooks}.
@end deffn
@deffn Command make-variable-buffer-local variable
@ -1116,6 +1153,12 @@ Note that storing new values into the @sc{cdr}s of cons cells in this
list does @emph{not} change the local values of the variables.
@end defun
@defun local-variable-p variable
This returns @code{t} if @var{variable} is buffer-local in the current
buffer. It is much faster to get the answer this way than to examine
the value of @code{buffer-local-variables}.
@end defun
@deffn Command kill-local-variable variable
This function deletes the buffer-local binding (if any) for
@var{variable} (a symbol) in the current buffer. As a result, the
@ -1277,4 +1320,3 @@ evaluated.
@end group
@end example
@end defun

27
lispref/windows.texi
View file

@ -659,8 +659,10 @@ Contrast this with @code{set-buffer}, which makes @var{buffer-or-name}
the current buffer but does not display it in the selected window.
@xref{Current Buffer}.
If @var{buffer-or-name} does not identify an existing buffer, then
a new buffer by that name is created.
If @var{buffer-or-name} does not identify an existing buffer, then a new
buffer by that name is created. The major mode for the new buffer is
set according to the variable @code{default-major-mode}. @xref{Auto
Major Mode}.
Normally the specified buffer is put at the front of the buffer list.
This affects the operation of @code{other-buffer}. However, if
@ -715,7 +717,9 @@ already displayed in the selected window and @var{other-window} is
for @var{buffer-or-name}, so that nothing needs to be done.
If @var{buffer-or-name} is a string that does not name an existing
buffer, a buffer by that name is created.
buffer, a buffer by that name is created. The major mode for the new
buffer is set according to the variable @code{default-major-mode}.
@xref{Auto Major Mode}.
@end defun
@node Choosing Window
@ -1520,6 +1524,23 @@ created narrower than this. The absolute minimum width is one; any
value below that is ignored. The default value is 10.
@end defopt
@defvar window-size-change-functions
This variable holds a list of functions to be called if the size of any
window changes for any reason. The functions are called just once per
redisplay, and just once for each frame on which size changes have
occurred.
Each function receives the frame as its sole argument. There is no
direct way to find out which windows changed size, or precisely how;
however, if your size-change function keeps track, after each change, of
the windows that interest you, you can figure out what has changed by
comparing the old size data with the new.
Creating or deleting windows counts as a size change, and therefore
causes these functions to be called. Changing the frame size also
counts, because it changes the sizes of the existing windows.
@end defvar
@node Coordinates and Windows
@section Coordinates and Windows