If the value is @code{nil}, abbrevs may be defined, but they are not
expanded automatically.
-This variable automatically becomes local when set in any fashion.
+This variable automatically becomes buffer-local when set in any fashion.
@end defvar
@defvar default-abbrev-mode
This is the local abbrev table used in Text mode.
@end defvar
-@defvar c-mode-abbrev-table
-This is the local abbrev table used in C mode.
-@end defvar
-
@defvar lisp-mode-abbrev-table
This is the local abbrev table used in Lisp mode and Emacs Lisp mode.
@end defvar
This means that if you insert text with text properties into the minibuffer,
the minibuffer value really will contain text properties.
+@item
+Only the simple menu item format is supported (@pxref{Simple Menu Items}).
+
@item
You can still bind @code{x-resource-class} around a call to
@code{x-get-resource}, but it won't do anything special.
know.
@item
-You can't do date arithmentic with @code{encode-time} any more.
+You can't do date arithmetic with @code{encode-time} any more.
@item
The functions @code{command-execute} and @code{call-interactively} no
@smallexample
@group
(defun make-backup-file-name (file)
- "Create the non-numeric backup file name for FILE.
-@dots{}"
+ "Create the non-numeric backup file name for FILE@enddots{}"
(concat file "~"))
@end group
@end smallexample
@group
(defun make-auto-save-file-name ()
"Return file name to use for auto-saves \
-of current buffer.
-@dots{}"
+of current buffer@enddots{}"
(if buffer-file-name
@end group
@group
used to detect a substantial decrease in size, and turn off auto-saving
in response.
-If it is -1, that means auto-saving is temporarily shut off in this
+If it is @minus{}1, that means auto-saving is temporarily shut off in this
buffer due to a substantial deletion. Explicitly saving the buffer
stores a positive value in this variable, thus reenabling auto-saving.
Turning auto-save mode off or on also alters this variable.
@end example
@noindent
-This function binds a local variable to the current buffer, and then
-@code{save-current-buffer} records which buffer that was. Next,
-@code{set-buffer} makes another buffer current. Finally,
+This function binds a local variable to record the current buffer, and
+then @code{save-current-buffer} arranges to make it current again.
+Next, @code{set-buffer} makes the specified buffer current. Finally,
@code{insert-buffer-substring} copies the string from the original
-current buffer to the new current buffer.
+current buffer to the specified (and now 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
@tindex save-current-buffer
@defmac save-current-buffer body...
The @code{save-current-buffer} macro saves the identity of the current
-buffer, evaluates the @var{body} forms, and finally restores the buffer.
-The return value is the value of the last form in @var{body}. The
-current buffer is restored even in case of an abnormal exit via
-@code{throw} or error (@pxref{Nonlocal Exits}).
+buffer, evaluates the @var{body} forms, and finally restores that buffer
+as current. The return value is the value of the last form in
+@var{body}. The current buffer is restored even in case of an abnormal
+exit via @code{throw} or error (@pxref{Nonlocal Exits}).
If the buffer that used to be current has been killed by the time of
exit from @code{save-current-buffer}, then it is not made current again,
@end example
It is risky to change this variable's value without doing various other
-things. See the definition of @code{set-visited-file-name} in
-@file{files.el}; some of the things done there, such as changing the
-buffer name, are not strictly necessary, but others are essential to
-avoid confusing Emacs.
+things. Normally it is better to use @code{set-visited-file-name} (see
+below); some of the things done there, such as changing the buffer name,
+are not strictly necessary, but others are essential to avoid confusing
+Emacs.
@end defvar
@defvar buffer-file-truename
This buffer-local variable holds the file number and directory device
number of the file visited in the current buffer, or @code{nil} if no
file or a nonexistent file is visited. It is a permanent local,
-unaffected by @code{kill-local-variables}. @xref{Truenames}.
+unaffected by @code{kill-local-variables}.
The value is normally a list of the form @code{(@var{filenum}
@var{devnum})}. This pair of numbers uniquely identifies the file among
@c Wordy to avoid overfull hbox. --rjc 16mar92
When the function @code{set-visited-file-name} is called interactively, it
prompts for @var{filename} in the minibuffer.
-
-See also @code{clear-visited-file-modtime} and
-@code{verify-visited-file-modtime} in @ref{Buffer Modification}.
@end deffn
@defvar list-buffers-directory
@code{other-buffer}, use this ordering. A buffer list displayed for the
user also follows this order.
-@defun buffer-list &optional frame
-This function returns a list of all buffers, including those whose names
-begin with a space. The elements are actual buffers, not their names.
+ In addition to the fundamental Emacs buffer list, each frame has its
+own version of the buffer list, in which the buffers that have been
+selected in that frame come first, starting with the buffers most
+recently selected @emph{in that frame}. (This order is recorded in
+@var{frame}'s @code{buffer-list} frame parameter; see @ref{Window Frame
+Parameters}.) The buffers that were never selected in @var{frame} come
+afterward, ordered according to the fundamental Emacs buffer list.
-If @var{frame} is @code{nil}, all the buffers appear in order of most
-recent selection, regardless of which frames they were selected in.
+@defun buffer-list &optional frame
+This function returns the buffer list, including all buffers, even those
+whose names begin with a space. The elements are actual buffers, not
+their names.
-If @var{frame} is a frame, then the buffers that have been selected in
-@var{frame} all come at the front of the list, ordered by most recent
-selection in @var{frame}. (This order is recorded in @var{frame}'s
-@code{buffer-list} frame parameter; see @ref{X Frame Parameters}.) The
-buffers that were never selected in @var{frame} come afterward, ordered
-according to most recent selection in other frames.
+If @var{frame} is a frame, this returns @var{frame}'s buffer list. If
+@var{frame} is @code{nil}, the fundamental Emacs buffer list is used:
+all the buffers appear in order of most recent selection, regardless of
+which frames they were selected in.
@example
@group
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
+if the value is @code{nil}, that buffer is ignored. @xref{Window Frame
Parameters}.
@c Emacs 19 feature
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
+overlays for both), different major modes, and different buffer-local
variables.
An indirect buffer cannot visit a file, but its base buffer can. If
@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 1990, 1991, 1992, 1993, 1995, 1998 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
-@node Calendar, Tips, Display, Top
+@node Calendar, System Interface, Display, Top
@chapter Customizing the Calendar and Diary
There are many customizations that you can use to make the calendar and
@item s
Arbitrary text, read in the minibuffer and returned as a string
(@pxref{Text from Minibuffer}). Terminate the input with either
-@key{LFD} or @key{RET}. (@kbd{C-q} may be used to include either of
+@kbd{C-j} or @key{RET}. (@kbd{C-q} may be used to include either of
these characters in the input.) Prompt.
@item S
@item x
A Lisp object, specified with its read syntax, terminated with a
-@key{LFD} or @key{RET}. The object is not evaluated. @xref{Object from
+@kbd{C-j} or @key{RET}. The object is not evaluated. @xref{Object from
Minibuffer}. Prompt.
@item X
(non-@code{nil} fourth argument to @code{autoload}), and some of the
primitive functions.
-A symbol is @code{commandp} if its function definition is
+A symbol satisfies @code{commandp} if its function definition satisfies
@code{commandp}.
Keys and keymaps are not commands. Rather, they are used to look up
an argument. @xref{Command History}.
The argument @var{keys}, if given, specifies the sequence of events to
-use if the command inquires which events were used to invoke it.
+supply if the command inquires which events were used to invoke it.
@end defun
@defun command-execute command &optional record-flag keys
rechecking the definition of the symbol.
The argument @var{keys}, if given, specifies the sequence of events to
-use if the command inquires which events were used to invoke it.
+supply if the command inquires which events were used to invoke it.
@end defun
@deffn Command execute-extended-command prefix-argument
directly from the editor command loop.) If the containing function was
called by Lisp evaluation (or with @code{apply} or @code{funcall}), then
it was not called interactively.
+@end defun
-The most common use of @code{interactive-p} is for deciding whether to
+ The most common use of @code{interactive-p} is for deciding whether to
print an informative message. As a special exception,
@code{interactive-p} returns @code{nil} whenever a keyboard macro is
being run. This is to suppress the informative messages and speed
execution of the macro.
-For example:
+ For example:
@example
@group
(defun foo ()
(interactive)
- (and (interactive-p)
- (message "foo")))
+ (when (interactive-p)
+ (message "foo")))
@result{} foo
@end group
@result{} (nil t)
@end group
@end example
-@end defun
+
+ The other way to do this sort of job is to make the command take an
+argument @code{print-message} which should be non-@code{nil} in an
+interactive call, and use the @code{interactive} spec to make sure it is
+non-@code{nil}. Here's how:
+
+@example
+(defun foo (&optional print-message)
+ (interactive "p")
+ (when print-message
+ (message "foo")))
+@end example
+
+ The numeric prefix argument, provided by @samp{p}, is never @code{nil}.
@node Command Loop Info
@comment node-name, next, previous, up
@end example
@end defun
+@defun this-command-keys-vector
+Like @code{this-command-keys}, except that it always returns
+the events in a vector, so you do never need to deal with the complexities
+of storing input events in a string (@pxref{Strings of Events}).
+@end defun
+
@defvar last-nonmenu-event
-This variable holds the last input event read as part of a key
-sequence, not counting events resulting from mouse menus.
+This variable holds the last input event read as part of a key sequence,
+not counting events resulting from mouse menus.
One use of this variable is for telling @code{x-popup-menu} where to pop
-up a menu.
+up a menu. It is also used internally by @code{y-or-n-p}
+(@pxref{Yes-or-No Queries}).
@end defvar
@defvar last-command-event
There are two kinds of input you can get from the keyboard: ordinary
keys, and function keys. Ordinary keys correspond to characters; the
-events they generate are represented in Lisp as characters. In Emacs
-versions 18 and earlier, characters were the only events. The event
-type of a character event is the character itself (an integer);
-see @ref{Classifying Events}.
+events they generate are represented in Lisp as characters. The event
+type of a character event is the character itself (an integer); see
+@ref{Classifying Events}.
@cindex modifier bits (of input character)
@cindex basic code (of input character)
@table @asis
@item meta
The
-@iftex
+@tex
$2^{27}$
-@end iftex
+@end tex
@ifinfo
2**27
@end ifinfo
@item control
The
-@iftex
+@tex
$2^{26}$
-@end iftex
+@end tex
@ifinfo
2**26
@end ifinfo
But if you type a control combination not in @sc{ASCII}, such as
@kbd{%} with the control key, the numeric value you get is the code
for @kbd{%} plus
-@iftex
+@tex
$2^{26}$
-@end iftex
+@end tex
@ifinfo
2**26
@end ifinfo
@item shift
The
-@iftex
+@tex
$2^{25}$
-@end iftex
+@end tex
@ifinfo
2**25
@end ifinfo
for digits and punctuation, the shift key selects an entirely different
character with a different basic code. In order to keep within the
@sc{ASCII} character set whenever possible, Emacs avoids using the
-@iftex
+@tex
$2^{25}$
-@end iftex
+@end tex
@ifinfo
2**25
@end ifinfo
However, @sc{ASCII} provides no way to distinguish @kbd{C-A} from
@kbd{C-a}, so Emacs uses the
-@iftex
+@tex
$2^{25}$
-@end iftex
+@end tex
@ifinfo
2**25
@end ifinfo
@item hyper
The
-@iftex
+@tex
$2^{24}$
-@end iftex
+@end tex
@ifinfo
2**24
@end ifinfo
@item super
The
-@iftex
+@tex
$2^{23}$
-@end iftex
+@end tex
@ifinfo
2**23
@end ifinfo
@item alt
The
-@iftex
+@tex
$2^{22}$
-@end iftex
+@end tex
@ifinfo
2**22
@end ifinfo
name contains the prefix @samp{down-}. The @samp{down-} prefix follows
modifier key prefixes such as @samp{C-} and @samp{M-}.
-The function @code{read-key-sequence}, and therefore the Emacs command
-loop as well, ignore any button-down events that don't have command
-bindings. This means that you need not worry about defining button-down
-events unless you want them to do something. The usual reason to define
-a button-down event is so that you can track mouse motion (by reading
-motion events) until the button is released. @xref{Motion Events}.
+The function @code{read-key-sequence} ignores any button-down events
+that don't have command bindings; therefore, the Emacs command loop
+ignores them too. This means that you need not worry about defining
+button-down events unless you want them to do something. The usual
+reason to define a button-down event is so that you can track mouse
+motion (by reading motion events) until the button is released.
+@xref{Motion Events}.
@node Repeat Events
@subsection Repeat Events
represented by lists that look like this:
@example
-(mouse-movement
- (@var{window} @var{buffer-pos} (@var{x} . @var{y}) @var{timestamp}))
+(mouse-movement (@var{window} @var{buffer-pos} (@var{x} . @var{y}) @var{timestamp}))
@end example
The second element of the list describes the current position of the
The special form @code{track-mouse} enables generation of motion events
within its body. Outside of @code{track-mouse} forms, Emacs does not
generate events for mere motion of the mouse, and these events do not
-appear.
-
-@defspec track-mouse body@dots{}
-This special form executes @var{body}, with generation of mouse motion
-events enabled. Typically @var{body} would use @code{read-event}
-to read the motion events and modify the display accordingly.
-
-When the user releases the button, that generates a click event.
-Typically, @var{body} should return when it sees the click event, and
-discard that event.
-@end defspec
+appear. @xref{Mouse Tracking}.
@node Focus Events
@subsection Focus Events
a mouse button or motion event.
These two functions return the starting or ending position of a
-mouse-button event. The position is a list of this form:
+mouse-button event, as a list of this form:
@example
(@var{window} @var{buffer-position} (@var{x} . @var{y}) @var{timestamp})
position such events have.
@end defun
- These five functions take a position as described above, and return
-various parts of it.
+ These five functions take a position list as described above, and
+return various parts of it.
@defun posn-window position
Return the window that @var{position} is in.
Return the timestamp in @var{position}.
@end defun
+ These functions are useful for decoding scroll bar events.
+
@defun scroll-bar-event-ratio event
This function returns the fractional vertical position of a scroll bar
event within the scroll bar. The value is a cons cell
string as containing text characters---the same kind of characters found
in buffers or files. Occasionally Lisp programs use strings that
conceptually contain keyboard characters; for example, they may be key
-sequences or keyboard macro definitions. There are special rules for
-how to put keyboard characters into a string, because they are not
-limited to the range of 0 to 255 as text characters are.
+sequences or keyboard macro definitions. However, storing keyboard
+characters in a string is a complex matter, for reasons of historical
+compatibility, and it is not always possible.
+
+ We recommend that new programs avoid dealing with these complexities
+by not storing keyboard events in strings. Here is how to do that:
+
+@itemize @bullet
+@item
+Use vectors instead of strings for key sequences, when you plan to use
+them for anything other than as arguments @code{lookup-key} and
+@code{define-key}. For example, you can use
+@code{read-key-sequence-vector} instead of @code{read-key-sequence}, and
+@code{this-command-keys-vector} instead of @code{this-command-keys}.
+
+@item
+Use vectors to write key sequence constants containing meta characters,
+even when passing them directly to @code{define-key}.
+
+@item
+When you have to look at the contents of a key sequence that might be a
+string, use @code{listify-key-sequence} (@pxref{Event Input Misc})
+first, to convert it to a list.
+@end itemize
- A keyboard character typed using the @key{META} key is called a
-@dfn{meta character}. The numeric code for such an event includes the
-@iftex
+ The complexities stem from the modifier bits that keyboard input
+characters can include. Aside from the Meta modifier, none of these
+modifier bits can be included in a string, and the Meta modifier is
+allowed only in special cases.
+
+ The earliest GNU Emacs versions represented meta characters as codes
+in the range of 128 to 255. At that time, the basic character codes
+ranged from 0 to 127, so all keyboard character codes did fit in a
+string. Many Lisp programs used @samp{\M-} in string constants to stand
+for meta characters, especially in arguments to @code{define-key} and
+similar functions, and key sequences and sequences of events were always
+represented as strings.
+
+ When we added support for larger basic character codes beyond 127, and
+additional modifier bits, we had to change the representation of meta
+characters. Now the flag that represents the Meta modifier in a
+character is
+@tex
$2^{27}$
-@end iftex
+@end tex
@ifinfo
2**27
@end ifinfo
-bit; it does not even come close to fitting in a string. However,
-earlier Emacs versions used a different representation for these
-characters, which gave them codes in the range of 128 to 255. That did
-fit in a string, and many Lisp programs contain string constants that
-use @samp{\M-} to express meta characters, especially as the argument to
-@code{define-key} and similar functions.
+and such numbers cannot be included in a string.
- We provide backward compatibility to run those programs using special
-rules for how to put a keyboard character event in a string. Here are
-the rules:
+ To support programs with @samp{\M-} in string constants, there are
+special rules for including certain meta characters in a string.
+Here are the rules for interpreting keyboard
@itemize @bullet
@item
@item
The meta variants of those characters, with codes in the range of
-@iftex
+@tex
$2^{27}$
-@end iftex
+@end tex
@ifinfo
2**27
@end ifinfo
to
-@iftex
+@tex
$2^{27} + 127$,
-@end iftex
+@end tex
@ifinfo
2**27+127,
@end ifinfo
can also go in the string, but you must change their
numeric values. You must set the
-@iftex
+@tex
$2^{7}$
-@end iftex
+@end tex
@ifinfo
2**7
@end ifinfo
bit instead of the
-@iftex
+@tex
$2^{27}$
-@end iftex
+@end tex
@ifinfo
2**27
@end ifinfo
-bit,
-resulting in a value between 128 and 255.
+bit, resulting in a value between 128 and 255. Only a unibyte string
+can include these codes.
+
+@item
+Non-@sc{ASCII} characters above 256 can be included in a multibyte string.
@item
Other keyboard character events cannot fit in a string. This includes
meta events in strings work consistently regardless of how they get into
the strings.
- The reason we changed the representation of meta characters as
-keyboard events is to make room for basic character codes beyond 127,
-and support meta variants of such larger character codes.
-
- New programs can avoid dealing with these special compatibility rules
-by using vectors instead of strings for key sequences when there is any
-possibility that they might contain meta characters, and by using
-@code{listify-key-sequence} to access a string of events.
-
-@defun listify-key-sequence key
-This function converts the string or vector @var{key} to a list of
-events, which you can put in @code{unread-command-events}. Converting a
-vector is simple, but converting a string is tricky because of the
-special representation used for meta characters in a string.
-@end defun
+ However, most programs would do well to avoid these issues by
+following the recommendations at the beginning of this section.
@node Reading Input
@section Reading Input
- The editor command loop reads keyboard input using the function
+ The editor command loop reads key sequences using the function
@code{read-key-sequence}, which uses @code{read-event}. These and other
-functions for keyboard input are also available for use in Lisp
-programs. See also @code{momentary-string-display} in @ref{Temporary
-Displays}, and @code{sit-for} in @ref{Waiting}. @xref{Terminal Input},
-for functions and variables for controlling terminal input modes and
+functions for event input are also available for use in Lisp programs.
+See also @code{momentary-string-display} in @ref{Temporary Displays},
+and @code{sit-for} in @ref{Waiting}. @xref{Terminal Input}, for
+functions and variables for controlling terminal input modes and
debugging terminal input. @xref{Translating Input}, for features you
can use for translating or modifying input events while reading them.
events---characters, symbols, and lists. The elements of the string or
vector are the events in the key sequence.
-The function @code{read-key-sequence} suppresses quitting: @kbd{C-g}
-typed while reading with this function works like any other character,
-and does not set @code{quit-flag}. @xref{Quitting}.
-
The argument @var{prompt} is either a string to be displayed in the echo
area as a prompt, or @code{nil}, meaning not to display a prompt.
@result{} "^X^F"
@end group
@end example
+
+The function @code{read-key-sequence} suppresses quitting: @kbd{C-g}
+typed while reading with this function works like any other character,
+and does not set @code{quit-flag}. @xref{Quitting}.
+@end defun
+
+@defun read-key-sequence-vector prompt
+This is like @code{read-key-sequence} except that it always
+returns the key sequence as a vector, never as a string.
+@xref{Strings of Events}.
@end defun
@cindex upper case key sequence
@cindex control characters, reading
@cindex nonprinting characters, reading
This function is like @code{read-char}, except that if the first
-character read is an octal digit (0-7), it reads up to two more octal digits
-(but stopping if a non-octal digit is found) and returns the
-character represented by those digits in octal.
+character read is an octal digit (0-7), it reads any number of octal
+digits (but stopping if a non-octal digit is found), and returns the
+character represented by that numeric character code.
Quitting is suppressed when the first character is read, so that the
user can enter a @kbd{C-g}. @xref{Quitting}.
most recently unread will be reread first.
@end defvar
+@defun listify-key-sequence key
+This function converts the string or vector @var{key} to a list of
+individual events, which you can put in @code{unread-command-events}.
+@end defun
+
@defvar unread-command-char
This variable holds a character to be read as command input.
A value of -1 means ``empty''.
@end defun
@defvar last-input-event
+@defvarx last-input-char
This variable records the last terminal input event read, whether
as part of a command or explicitly by a Lisp program.
@end group
@end example
-@vindex last-input-char
The alias @code{last-input-char} exists for compatibility with
Emacs version 18.
@end defvar
does not cause a quit; it acts as an ordinary input character. In the
simplest case, you cannot tell the difference, because @kbd{C-g}
normally runs the command @code{keyboard-quit}, whose effect is to quit.
-However, when @kbd{C-g} follows a prefix key, the result is an undefined
-key. The effect is to cancel the prefix key as well as any prefix
-argument.
+However, when @kbd{C-g} follows a prefix key, they combine to form an
+undefined key. The effect is to cancel the prefix key as well as any
+prefix argument.
In the minibuffer, @kbd{C-g} has a different definition: it aborts out
of the minibuffer. This means, in effect, that it exits the minibuffer
@example
(defun read-quoted-char (&optional prompt)
"@dots{}@var{documentation}@dots{}"
- (let ((count 0) (code 0) char)
- (while (< count 3)
- (let ((inhibit-quit (zerop count))
- (help-form nil))
- (and prompt (message "%s-" prompt))
- (setq char (read-char))
- (if inhibit-quit (setq quit-flag nil)))
- @dots{})
- (logand 255 code)))
+ (let ((message-log-max nil) done (first t) (code 0) char)
+ (while (not done)
+ (let ((inhibit-quit first)
+ @dots{})
+ (and prompt (message "%s-" prompt))
+ (setq char (read-event))
+ (if inhibit-quit (setq quit-flag nil)))
+ @r{@dots{}set the variable @code{code}@dots{}})
+ code))
@end example
@defvar quit-flag
@c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/compile
-@node Byte Compilation, Debugging, Loading, Top
+@node Byte Compilation, Advising, Loading, Top
@chapter Byte Compilation
@cindex byte-code
@cindex compilation
- GNU Emacs Lisp has a @dfn{compiler} that translates functions written
+ Emacs Lisp has a @dfn{compiler} that translates functions written
in Lisp into a special representation called @dfn{byte-code} that can be
executed more efficiently. The compiler replaces Lisp function
definitions with byte-code. When a byte-code function is called, its
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 19.29, the compiled
-code does not run in earlier versions.
+by recent earlier versions of Emacs, but the reverse is not true. A
+major incompatible change was introduced in Emacs version 19.29, and
+files compiled with versions since that one will definitely not run
+in earlier versions unless you specify a special option.
@iftex
@xref{Docs and Compilation}.
@end iftex
-Files compiled in versions before 19.29 may not work in 19.29 if they
-contain character constants with modifier bits, because the bits were
-renumbered in Emacs 19.29.
+In addition, the modifier bits in keyboard characters were renumbered in
+Emacs 19.29; as a result, files compiled in versions before 19.29 will
+not work in subsequent versions if they contain character constants with
+modifier bits.
@xref{Compilation Errors}, for how to investigate errors occurring in
byte compilation.
program that suggest a problem but are not necessarily erroneous.
@cindex macro compilation
- Be careful when byte-compiling code that uses macros. Macro calls are
-expanded when they are compiled, so the macros must already be defined
-for proper compilation. For more details, see @ref{Compiling Macros}.
+ Be careful when writing macro calls in files that you may someday
+byte-compile. Macro calls are expanded when they are compiled, so the
+macros must already be defined for proper compilation. For more
+details, see @ref{Compiling Macros}.
Normally, compiling a file does not evaluate the file's contents or
load the file. But it does execute any @code{require} calls at top
needs recompilation. A file needs recompilation if a @samp{.elc} file
exists but is older than the @samp{.el} file.
-When a @samp{.el} file has no corresponding @samp{.elc} file, then
-@var{flag} says what to do. If it is @code{nil}, these files are
-ignored. If it is non-@code{nil}, the user is asked whether to compile
-each such file.
+When a @samp{.el} file has no corresponding @samp{.elc} file, @var{flag}
+says what to do. If it is @code{nil}, these files are ignored. If it
+is non-@code{nil}, the user is asked whether to compile each such file.
The returned value of this command is unpredictable.
@end deffn
@cindex byte-code interpreter
This function actually interprets byte-code. A byte-compiled function
is actually defined with a body that calls @code{byte-code}. Don't call
-this function yourself. Only the byte compiler knows how to generate
+this function yourself---only the byte compiler knows how to generate
valid calls to this function.
-In newer Emacs versions (19 and up), byte-code is usually executed as
-part of a byte-code function object, and only rarely due to an explicit
-call to @code{byte-code}.
+In Emacs version 18, byte-code was always executed by way of a call to
+the function @code{byte-code}. Nowadays, byte-code is usually executed
+as part of a byte-code function object, and only rarely through an
+explicit call to @code{byte-code}.
@end defun
@node Docs and Compilation
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 to do that:
+ Byte-compiled files made with recent versions of Emacs (since 19.29)
+will not load into older versions because the older versions don't
+support this feature. You can turn off this feature at compile time by
+setting @code{byte-compile-dynamic-docstrings} to @code{nil}; then 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. One way to do that is by adding this string to the
+file's first line:
@example
-*-byte-compile-dynamic-docstrings: nil;-*-
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.
+string.'' It is usually best not to use these constructs in Lisp source
+files, since they are not designed to be clear to humans reading the
+file.
@node Dynamic Loading
@section Dynamic Loading of Individual Functions
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.
+many separate user-callable functions, if using one of them does not
+imply you will probably also 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:
@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
+then trying to load any function not already loaded will yield 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.
+ These problems will never happen in normal circumstances with
+installed Emacs files. But they are quite likely to happen with Lisp
+files that you are changing. The easiest way to prevent these problems
+is to reload the new compiled file immediately after each recompilation.
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:
+specific source files with file-local variable bindings. For example,
+you could do it by writing this text in the source file's first line:
@example
-*-byte-compile-dynamic: t;-*-
containing code and when you run it (whether compiled or not).
You can get a similar result by putting @var{body} in a separate file
-and referring to that file with @code{require}. Using @code{require} is
-preferable if there is a substantial amount of code to be executed in
-this way.
+and referring to that file with @code{require}. That method is
+preferable when @var{body} is large.
@end defspec
@defspec eval-when-compile body
you load the source file, rather than compiling it, @var{body} is
evaluated normally.
-At top level, this is analogous to the Common Lisp idiom
-@code{(eval-when (compile eval) @dots{})}. Elsewhere, the Common Lisp
-@samp{#.} reader macro (but not when interpreting) is closer to what
-@code{eval-when-compile} does.
+@strong{Common Lisp Note:} At top level, this is analogous to the Common
+Lisp idiom @code{(eval-when (compile eval) @dots{})}. Elsewhere, the
+Common Lisp @samp{#.} reader macro (but not when interpreting) is closer
+to what @code{eval-when-compile} does.
@end defspec
@node Byte-Code Objects
function object is like that for a vector, with an additional @samp{#}
before the opening @samp{[}.
- In Emacs version 18, there was no byte-code function object data type;
-compiled functions used the function @code{byte-code} to run the byte
-code.
-
A byte-code function object must have at least four elements; there is
-no maximum number, but only the first six elements are actually used.
+no maximum number, but only the first six elements have any normal use.
They are:
@table @var
@noindent
This moves forward one line and continues moving by lines until it
-reaches an empty. It is unusual in that the @code{while} has no body,
-just the end test (which also does the real work of moving point).
+reaches an empty line. It is peculiar in that the @code{while} has no
+body, just the end test (which also does the real work of moving point).
@end defspec
@node Nonlocal Exits
@example
@group
-(error "You have committed an error.
- Try something else.")
- @error{} You have committed an error.
- Try something else.
+(error "That is an error -- try something else")
+ @error{} That is an error -- try something else
@end group
@group
-(error "You have committed %d errors." 10)
- @error{} You have committed 10 errors.
+(error "You have committed %d errors" 10)
+ @error{} You have committed 10 errors
@end group
@end example
The number and significance of the objects in @var{data} depends on
@var{error-symbol}. For example, with a @code{wrong-type-arg} error,
-there are two objects in the list: a predicate that describes the type
+there should be two objects in the list: a predicate that describes the type
that was expected, and the object that failed to fit that type.
@xref{Error Symbols}, for a description of error symbols.
@end group
@group
-(signal 'no-such-error '("My unknown error condition."))
- @error{} peculiar error: "My unknown error condition."
+(signal 'no-such-error '("My unknown error condition"))
+ @error{} peculiar error: "My unknown error condition"
@end group
@end smallexample
@end defun
bindings that were made within the protected form. All it can do is
clean up and proceed.
- @code{condition-case} is often used to trap errors that are
-predictable, such as failure to open a file in a call to
+ The @code{condition-case} construct is often used to trap errors that
+are predictable, such as failure to open a file in a call to
@code{insert-file-contents}. It is also used to trap errors that are
totally unpredictable, such as when the program evaluates an expression
read from the user.
However, the way shown above is safer, if @var{body} happens to get an
error after switching to a different buffer! (Alternatively, you could
write another @code{save-excursion} around the body, to ensure that the
-temporary buffer becomes current in time to kill it.)
+temporary buffer becomes current again in time to kill it.)
+
+ Emacs includes a standard macro called @code{with-temp-buffer} which
+expands into more or less the code shown above (@pxref{Current Buffer}).
+Several of the macros defined in this manual use @code{unwind-protect}
+in this way.
@findex ftp-login
Here is an actual example taken from the file @file{ftp.el}. It
@code{ftp-setup-buffer} returns but before the variable @code{process} is
set, the process will not be killed. There is no easy way to fix this bug,
but at least it is very unlikely.
-
- Here is another example which uses @code{unwind-protect} to make sure
-to kill a temporary buffer. In this example, the value returned by
-@code{unwind-protect} is used.
-
-@smallexample
-(defun shell-command-string (cmd)
- "Return the output of the shell command CMD, as a string."
- (save-excursion
- (set-buffer (generate-new-buffer " OS*cmd"))
- (shell-command cmd t)
- (unwind-protect
- (buffer-string)
- (kill-buffer (current-buffer)))))
-@end smallexample
@node Customization, Loading, Macros, Top
@chapter Writing Customization Definitions
-This chapter describes how to declare customization groups, variables,
-and faces. We use the term @dfn{customization item} to include all
-three of those. This has few examples, but please look at the file
-@file{cus-edit.el}, which contains many declarations you can learn from.
+ This chapter describes how to declare user options for customization,
+and also customization groups for classifying them. We use the term
+@dfn{customization item} to include both kinds of customization
+definitions---as well as face definitions (@pxref{Defining Faces}).
@menu
* Common Keywords::
* Group Definitions::
* Variable Definitions::
-* Face Definitions::
* Customization Types::
@end menu
@node Common Keywords
@section Common Keywords for All Kinds of Items
-All three kinds of customization declarations (for groups, variables,
-and faces) accept keyword arguments for specifying various information.
-This section describes some keywords that apply to all three.
+ All kinds of customization declarations (for variables and groups, and
+for faces) accept keyword arguments for specifying various information.
+This section describes some keywords that apply to all kinds.
-All of these keywords, except @code{:tag}, can be used more than once in
-a given item. Each use of the keyword has an independent effect. The
-keyword @code{:tag} is an exception because any given item can only
-display one name item.
+ All of these keywords, except @code{:tag}, can be used more than once
+in a given item. Each use of the keyword has an independent effect.
+The keyword @code{:tag} is an exception because any given item can only
+display one name.
@table @code
@item :group @var{group}
There are three alternatives you can use for @var{link-data}:
@table @code
+@item :tag @var{name}
+Use @var{name}, a string, instead of the item's name, to label the item
+in customization menus and buffers.
+
@item (custom-manual @var{info-node})
Link to an Info node; @var{info-node} is a string which specifies the
node name, as in @code{"(emacs)Top"}. The link appears as
in the customization buffer with the Info node name.
@item (url-link @var{url})
-Link to a web page; @var{url} is a string which specifies the URL. The
-link appears in the customization buffer as @var{url}.
+Link to a web page; @var{url} is a string which specifies the @sc{url}.
+The link appears in the customization buffer as @var{url}.
@end table
You can specify the text to use in the customization buffer by adding
The most common reason to use @code{:require} is when a variable enables
a feature such as a minor mode, and just setting the variable won't have
any effect unless the code which implements the mode is loaded.
-
-@item :tag @var{name}
-Use @var{name}, a string, instead of the item's name, to label the item
-in customization menus and buffers.
@end table
@node Group Definitions
@section Defining Custom Groups
-Each Emacs Lisp package should have one main customization group which
+ Each Emacs Lisp package should have one main customization group which
contains all the options, faces and other groups in the package. If the
package has a small number of options and faces, use just one group and
put everything in it. When there are more than twelve or so options and
faces, then you should structure them into subgroups, and put the
-subgroups under the package's main customization group. It is ok to
-have some of the options and faces in the package's main group alongside
+subgroups under the package's main customization group. It is OK to
+put some of the options and faces in the package's main group alongside
the subgroups.
-The package's main or only group should be a member of one or more of
-the standard customization groups. Type press @kbd{C-h p} to display a
-list of finder keywords; them choose some of them add your group to each
-of them, using the @code{:group} keyword.
+ The package's main or only group should be a member of one or more of
+the standard customization groups. (To display the full list of them,
+use @kbd{M-x customize}.) Choose one or more of them (but not too
+many), and add your group to each of them using the @code{:group}
+keyword.
-The way to declare new customization groups is with @code{defgroup}.
+ The way to declare new customization groups is with @code{defgroup}.
@tindex defgroup
@defmac defgroup group members doc [keyword value]...
the documentation string for the group.
The arguments @var{members} can be an alist whose elements specify
-members of the group; however, normally @var{members} is @code{nil}, and
-you specify the group's members by using the @code{:group} keyword when
-defining those members.
+customization items to be members of the group; however, normally
+@var{members} is @code{nil}, and you specify the group's members by
+using the @code{:group} keyword when defining those members.
@ignore
@code{(@var{name} @var{widget})}. Here @var{name} is a symbol, and
@end table
@end defmac
-The @code{:prefix} feature is currently turned off, which means that
-@code{:prefix} currently has no effect. We did this because we found
-that discarding the specified prefixes often led to confusing names for
-options. This happened because the people who wrote the @code{defgroup}
-definitions for various groups added @code{:prefix} keywords whenever
-they make logical sense---that is, whenever they say that there was a
-common prefix for the option names in a library.
-
-In order to obtain good results with @code{:prefix}, it is necessary to
-check the specific effects of discarding a particular prefix, given the
-specific items in a group and their names and documentation. If the
-resulting text is not clear, then @code{:prefix} should not be used in
-that case.
-
-It should be possible to recheck all the customization groups, delete
+ The prefix-discarding feature is currently turned off, which means
+that @code{:prefix} currently has no effect. We did this because we
+found that discarding the specified prefixes often led to confusing
+names for options. This happened because the people who wrote the
+@code{defgroup} definitions for various groups added @code{:prefix}
+keywords whenever they make logical sense---that is, whenever the
+variables in the library have a common prefix.
+
+ In order to obtain good results with @code{:prefix}, it would be
+necessary to check the specific effects of discarding a particular
+prefix, given the specific items in a group and their names and
+documentation. If the resulting text is not clear, then @code{:prefix}
+should not be used in that case.
+
+ It should be possible to recheck all the customization groups, delete
the @code{:prefix} specifications which give unclear results, and then
turn this feature back on, if someone would like to do the work.
@node Variable Definitions
@section Defining Customization Variables
- Use @code{defcustom} to declare user editable variables.
+ Use @code{defcustom} to declare user-editable variables.
@tindex defcustom
-@defmac defcustom option value doc [keyword value]...
-Declare @var{option} as a customizable user option variable that
-defaults to @var{value}. Do not quote @var{option}. @var{value} should
-be an expression to compute the value; it will be be evaluated on more
+@defmac defcustom option default doc [keyword value]...
+Declare @var{option} as a customizable user option variable. Do not
+quote @var{option}. The argument @var{doc} specifies the documentation
+string for the variable.
+
+If @var{option} is void, @code{defcustom} initializes it to
+@var{default}. @var{default} should be an expression to compute the
+value; be careful in writing it, because it can be be evaluated on more
than one occasion.
-If @var{option} is void, @code{defcustom} initializes it to @var{value}.
-
-The argument @var{doc} specifies the documentation string for the variable.
-
The following additional keywords are defined:
@table @code
Specify @var{list} as the list of reasonable values for use in this
option.
-Currently this is meaningful only when type is @code{hook}. The
-elements of @var{list} are functions that you might likely want to use
-as elements of the hook value. The user is not actually restricted to
-using only these functions, but they are offered as convenient
-alternatives.
+Currently this is meaningful only when the type is @code{hook}. In that
+case, the elements of @var{list} should be functions that are useful as
+elements of the hook value. The user is not restricted to using only
+these functions, but they are offered as convenient alternatives.
@item :version @var{version}
This option specifies that the variable's default value was changed in
@table @code
@item custom-initialize-set
-Use the variable's @code{:set} function to initialize the variable. Do
-not reinitialize it if it is already non-void. This is the default
+Use the variable's @code{:set} function to initialize the variable, but
+do not reinitialize it if it is already non-void. This is the default
@code{:initialize} function.
@item custom-initialize-default
-Always use @code{set-default} to initialize the variable, even if some
-other @code{:set} function has been specified.
+Like @code{custom-initialize-set}, but use the function
+@code{set-default} to set the variable, instead of the variable's
+@code{:set} function. This is the usual choice for a variable whose
+@code{:set} function enables or disables a minor mode; with this choice,
+defining the variable will not call the minor mode function, but
+customizing the variable will do so.
@item custom-initialize-reset
-Even if the variable is already non-void, reset it by calling the
-@code{:set} function using the current value (returned by the
-@code{:get} method).
+Always use the @code{:set} function to initialize the variable. If the
+variable is already non-void, reset it by calling the @code{:set}
+function using the current value (returned by the @code{:get} method).
@item custom-initialize-changed
-Like @code{custom-initialize-reset}, except use @code{set-default}
-(rather than the @code{:set} function) to initialize the variable if it
-is not bound and has not been set already.
+Use the @code{:set} function to initialize the variable, if it is
+already set or has been customized; otherwise, just use
+@code{set-default}.
@end table
+@end table
+@end defmac
-@item :require @var{feature}
-If the user saves a customized value for this item, them Emacs should do
-@code{(require @var{feature})} after installing the saved value.
-
-The place to use this feature is for an option that turns on the
+ The @code{:require} option is useful for an option that turns on the
operation of a certain feature. Assuming that the package is coded to
check the value of the option, you still need to arrange for the package
-to be loaded. That is what @code{:require} is for.
-@end table
-@end defmac
+to be loaded. You can do that with @code{:require}. @xref{Common
+Keywords}. Here is an example, from the library @file{paren.el}:
+
+@example
+(defcustom show-paren-mode nil
+ "Toggle Show Paren mode@enddots{}"
+ :set (lambda (symbol value)
+ (show-paren-mode (or value 0)))
+ :initialize 'custom-initialize-default
+ :type 'boolean
+ :group 'paren-showing
+ :require 'paren)
+@end example
@ignore
Use @code{custom-add-option} to specify that a specific function is
customization buffer. The @code{saved-value} property is actually a
list whose car is an expression which evaluates to the value.
-@node Face Definitions
-@section Defining Faces
-
-Faces are declared with @code{defface}.
-
-@tindex defface
-@defmac defface face spec doc [keyword value]...
-Declare @var{face} as a customizable face that defaults according to
-@var{spec}. Do not quote the symbol @var{face}.
-
-@var{doc} is the face documentation.
-
-@var{spec} should be an alist whose elements have the form
-@code{(@var{display} @var{atts})} (see below). When @code{defface}
-executes, it defines the face according to @var{spec}, then uses any
-customizations saved in the @file{.emacs} file to override that
-specification.
-
-In each element of @var{spec}, @var{atts} is a list of face attributes
-and their values. The possible attributes are defined in the variable
-@code{custom-face-attributes}.
-
-The @var{display} part of an element of @var{spec} determines which
-frames the element applies to. If more than one element of @var{spec}
-matches a given frame, the first matching element is the only one used
-for that frame.
-
-If @var{display} is @code{t} in a @var{spec} element, that element
-matches all frames. (This means that any subsequent elements of
-@var{spec} are never used.)
-
-Alternatively, @var{display} can be an alist whose elements have the
-form @code{(@var{characteristic} @var{value}@dots{})}. Here
-@var{characteristic} specifies a way of classifying frames, and the
-@var{value}s are possible classifications which @var{display} should
-apply to. Here are the possible values of @var{characteristic}:
-
-@table @code
-@item type
-The kind of window system the frame uses---either @code{x}, @code{pc}
-(for the MS-DOS console), @code{w32} (for MS Windows 9X/NT), or
-@code{tty}.
-
-@item class
-What kinds of colors the frame supports---either @code{color},
-@code{grayscale}, or @code{mono}.
-
-@item background
-The kind of background--- either @code{light} or @code{dark}.
-@end table
-
-If an element of @var{display} specifies more than one
-@var{value} for a given @var{characteristic}, any of those values
-is acceptable. If an element of @var{display} has elements for
-more than one @var{characteristic}, then @var{each} characteristic
-of the frame must match one of the values specified for it.
-@end defmac
-
-Internally, @code{defface} uses the symbol property
-@code{face-defface-spec} to record the face attributes specified in
-@code{defface}, @code{saved-face} for the attributes saved by the user
-with the customization buffer, and @code{face-documentation} for the
-documentation string.
-
@node Customization Types
@section Customization Types
When you define a user option with @code{defcustom}, you must specify
-its @dfn{customization type}. That is a Lisp object which indictaes (1)
+its @dfn{customization type}. That is a Lisp object which describes (1)
which values are legitimate and (2) how to display the value in the
customization buffer for editing.
You specify the customization type in @code{defcustom} with the
@code{:type} keyword. The argument of @code{:type} is evaluated; since
-types that vary at run time are rarely useful, normally it is a quoted
+types that vary at run time are rarely useful, normally you use a quoted
constant. For example:
@example
(defcustom diff-command "diff"
"*The command to use to run diff."
- :type 'string
+ :type '(string)
:group 'diff)
@end example
- In general, a customization type appears is a list whose first element
-is a symbol, one of the customization type names defined in the
-following sections. After this symbol come a number of arguments,
-depending on the symbol. Some of the type symbols do not use any
-arguments; those are called @dfn{simple types}.
-
- In between the type symbol and its arguments, you can optionally
-write keyword-value pairs. @xref{Type Keywords}.
+ In general, a customization type is a list whose first element is a
+symbol, one of the customization type names defined in the following
+sections. After this symbol come a number of arguments, depending on
+the symbol. Between the type symbol and its arguments, you can
+optionally write keyword-value pairs (@pxref{Type Keywords}).
- For a simple type, if you do not use any keyword-value pairs, you can
-omit the parentheses around the type symbol. The above example does
-this, using just @code{string} as the customization type.
-But @code{(string)} would mean the same thing.
+ Some of the type symbols do not use any arguments; those are called
+@dfn{simple types}. For a simple type, if you do not use any
+keyword-value pairs, you can omit the parentheses around the type
+symbol. For example just @code{string} as a customization type is
+equivalent to @code{(string)}.
@menu
* Simple Types::
@item string
The value must be a string, and the customization buffer shows just the
-contents, with no @samp{"} characters or quoting with @samp{\}.
+contents, with no delimiting @samp{"} characters and no quoting with
+@samp{\}.
@item regexp
-The value must be a string which is a valid regular expression.
+Like @code{string} except that the string must be a valid regular
+expression.
@item character
The value must be a character code. A character code is actually an
@kbd{M-@key{TAB}}.
@item boolean
-The value is boolean---either @code{nil} or @code{t}.
+The value is boolean---either @code{nil} or @code{t}. Note that by
+using @code{choice} and @code{const} together (see the next section),
+you can specify that the value must be @code{nil} or @code{t}, but also
+specify the text to describe each value in a way that fits the specific
+meaning of the alternative.
@end table
@node Composite Types
@subsection Composite Types
When none of the simple types is appropriate, you can use composite
-types, which build from simple types. Here are several ways of doing
-that:
+types, which build new types from other types. Here are several ways of
+doing that:
@table @code
@item (restricted-sexp :match-alternatives @var{criteria})
@item
A quoted constant---that is, @code{'@var{object}}. This means that
-@var{object} is an acceptable value.
+@var{object} itself is an acceptable value.
@end itemize
For example,
symbol)} is a customization type which matches values such as
@code{("foo" . foo)}.
-In the customization buffeer, the @sc{car} and the @sc{cdr} are
+In the customization buffer, the @sc{car} and the @sc{cdr} are
displayed and edited separately, each according to the type
that you specify for it.
three elements; the first element must be an integer, the second a
string, and the third a function.
-In the customization buffeer, the each element is displayed and edited
+In the customization buffer, the each element is displayed and edited
separately, according to the type specified for it.
@item (vector @var{element-types}@dots{})
@noindent
so that the menu offers @samp{Number of spaces} and @samp{Literal Text}.
+In any alternative for which @code{nil} is not a valid value, other than
+a @code{const}, you should specify a valid default for that alternative
+using the @code{:value} keyword. @xref{Type Keywords}.
+
@item (const @var{value})
The value must be @var{value}---nothing else is allowed.
The main use of @code{const} is inside of @code{choice}. For example,
@code{(choice integer (const nil))} allows either an integer or
-@code{nil}. @code{:tag} is often used with @code{const}.
+@code{nil}.
+
+@code{:tag} is often used with @code{const}, inside of @code{choice}.
+For example,
+
+@smallexample
+(choice (const :tag "Yes" t)
+ (const :tag "No" nil)
+ (const :tag "Ask" foo))
+@end smallexample
@item (function-item @var{function})
Like @code{const}, but used for values which are functions. This
-displays the documentation string of the function @var{function}
-as well as its name.
+displays the documentation string as well as the function name.
+The documentation string is either the one you specify with
+@code{:doc}, or @var{function}'s own documentation string.
@item (variable-item @var{variable})
Like @code{const}, but used for values which are variable names. This
-displays the documentation string of the variable @var{variable} as well
-as its name.
+displays the documentation string as well as the variable name. The
+documentation string is either the one you specify with @code{:doc}, or
+@var{variable}'s own documentation string.
@item (set @var{elements}@dots{})
The value must be a list and each element of the list must be one of the
@table @code
@item :value @var{default}
This is used for a type that appears as an alternative inside of
-@code{:choice}; it specifies the default value to use, at first, if and
+@code{choice}; it specifies the default value to use, at first, if and
when the user selects this alternative with the menu in the
customization buffer.
Of course, if the actual value of the option fits this alternative, it
will appear showing the actual value, not @var{default}.
+If @code{nil} is not a valid value for the alternative, then it is
+essential to specify a valid default with @code{:value}.
+
@item :format @var{format-string}
This string will be inserted in the buffer to represent the value
corresponding to the type. The following @samp{%} escapes are available
for use in @var{format-string}:
@table @samp
-@ignore
@item %[@var{button}%]
Display the text @var{button} marked as a button. The @code{:action}
attribute specifies what the button will do if the user invokes it;
the button appears in, and the event.
There is no way to specify two different buttons with different
-actions; but perhaps there is no need for one.
-@end ignore
+actions.
@item %@{@var{sample}%@}
Show @var{sample} in a special face specified by @code{:sample-face}.
Display a literal @samp{%}.
@end table
+@item :action @var{action}
+Perform @var{action} if the user clicks on a button.
+
@item :button-face @var{face}
-Use face @var{face} for text displayed with @samp{%[@dots{}%]}.
+Use the face @var{face} (a face name or a list of face names) for button
+text displayed with @samp{%[@dots{}%]}.
-@item :button-prefix
-@itemx :button-suffix
+@item :button-prefix @var{prefix}
+@itemx :button-suffix @var{suffix}
These specify the text to display before and after a button.
Each can be:
The symbol's value is used.
@end table
+@item :tag @var{tag}
+Use @var{tag} (a string) as the tag for the value (or part of the value)
+that corresponds to this type.
+
@item :doc @var{doc}
-Use @var{doc} as the documentation string for this item.
+Use @var{doc} as the documentation string for this value (or part of the
+value) that corresponds to this type. In order for this to work, you
+must specify a value for @code{:format}, and use @samp{%d} or @samp{%h}
+in that value.
-@item :tag @var{tag}
-Use @var{tag} (a string) as the tag for this item.
+The usual reason to specify a documentation string for a type is to
+provide more information about the meanings of alternatives inside a
+@code{:choice} type or the parts of some other composite type.
@item :help-echo @var{motion-doc}
When you move to this item with @code{widget-forward} or
in the echo area.
@item :match @var{function}
-Specify how to decide whether a value matches the type. @var{function}
-should be a function that accepts two arguments, a widget and a value;
-it should return non-@code{nil} if the value is acceptable.
+Specify how to decide whether a value matches the type. The
+corresponding value, @var{function}, should be a function that accepts
+two arguments, a widget and a value; it should return non-@code{nil} if
+the value is acceptable.
@ignore
@item :indent @var{columns}
@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1998 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/debugging
-@node Debugging, Read and Print, Byte Compilation, Top
+@node Debugging, Read and Print, Advising, Top
@chapter Debugging Lisp Programs
There are three ways to investigate a problem in an Emacs Lisp program,
@code{debug-on-error}.
The normal value of this variable lists several errors that happen often
-during editing but rarely result from bugs in Lisp programs.
+during editing but rarely result from bugs in Lisp programs. However,
+``rarely'' is not ``never''; if your program fails with an error that
+matches this list, you will need to change this list in order to debug
+the error. The easiest way is usually to set
+@code{debug-ignored-errors} to @code{nil}.
@end defopt
@defopt debug-on-signal
Normally, errors that are caught by @code{condition-case} never run the
debugger, even if @code{debug-on-error} is non-@code{nil}. In other
-words, @code{condition-case} gets a chance to catch the error before the
-debugger gets a chance.
+words, @code{condition-case} gets a chance to handle the error before
+the debugger gets a chance.
If you set @code{debug-on-signal} non-@code{nil}, then the debugger gets
first chance at every error; an error will invoke the debugger
specified by the values of @code{debug-on-error} and
@code{debug-ignored-errors}.
-@strong{Warning:} This variable is strong medecine! Various parts of
+@strong{Warning:} This variable is strong medicine! Various parts of
Emacs handle errors in the normal course of affairs, and you may not
even realize that errors happen there. If you set
@code{debug-on-signal} to a non-@code{nil} value, those errors will
To debug an error that happens during loading of the @file{.emacs}
file, use the option @samp{-debug-init}, which binds
@code{debug-on-error} to @code{t} while @file{.emacs} is loaded and
-inhibits use of @code{condition-case} to catch init file errors.
+inhibits use of @code{condition-case} to catch init-file errors.
If your @file{.emacs} file sets @code{debug-on-error}, the effect may
not last past the end of loading @file{.emacs}. (This is an undesirable
function, and then step through its caller.
@deffn Command debug-on-entry function-name
- This function requests @var{function-name} to invoke the debugger each time
+This function requests @var{function-name} to invoke the debugger each time
it is called. It works by inserting the form @code{(debug 'debug)} into
the function definition as the first form.
- Any function defined as Lisp code may be set to break on entry,
+Any function defined as Lisp code may be set to break on entry,
regardless of whether it is interpreted code or compiled code. If the
function is a command, it will enter the debugger when called from Lisp
and when called interactively (after the reading of the arguments). You
can't debug primitive functions (i.e., those written in C) this way.
- When @code{debug-on-entry} is called interactively, it prompts
-for @var{function-name} in the minibuffer.
+When @code{debug-on-entry} is called interactively, it prompts for
+@var{function-name} in the minibuffer. If the function is already set
+up to invoke the debugger on entry, @code{debug-on-entry} does nothing.
+@code{debug-on-entry} always returns @var{function-name}.
- If the function is already set up to invoke the debugger on entry,
-@code{debug-on-entry} does nothing.
-
- @strong{Note:} if you redefine a function after using
-@code{debug-on-entry} on it, the code to enter the debugger is lost.
-
- @code{debug-on-entry} returns @var{function-name}.
+@strong{Note:} if you redefine a function after using
+@code{debug-on-entry} on it, the code to enter the debugger is discarded
+by the redefinition. In effect, redefining the function cancels
+the break-on-entry feature for that function.
@example
@group
This function undoes the effect of @code{debug-on-entry} on
@var{function-name}. When called interactively, it prompts for
@var{function-name} in the minibuffer. If @var{function-name} is
-@code{nil} or the empty string, it cancels debugging for all functions.
+@code{nil} or the empty string, it cancels break-on-entry for all
+functions.
-If @code{cancel-debug-on-entry} is called more than once on the same
-function, the second call does nothing. @code{cancel-debug-on-entry}
-returns @var{function-name}.
+Calling @code{cancel-debug-on-entry} does nothing to a function which is
+not currently set up to break on entry. It always returns
+@var{function-name}.
@end deffn
@node Explicit Debug
through the control structures of an interpreted function, but cannot do
so in a byte-compiled function. If you would like to step through a
byte-compiled function, replace it with an interpreted definition of the
-same function. (To do this, visit the source file for the function and
-type @kbd{C-M-x} on its definition.)
+same function. (To do this, visit the source for the function and type
+@kbd{C-M-x} on its definition.)
Here is a list of Debugger mode commands:
@item u
Don't enter the debugger when the current frame is exited. This
-cancels a @kbd{b} command on that frame.
+cancels a @kbd{b} command on that frame. The visible effect is to
+remove the star from the line in the backtrace buffer.
@item e
Read a Lisp expression in the minibuffer, evaluate it, and print the
@kbd{M-:} does nothing special in the debugger; it shows you the
variable values within the debugger.
+@item R
+Like @kbd{e}, but also save the result of evaluation in the
+buffer @samp{*Debugger-record*}.
+
@item q
Terminate the program being debugged; return to top-level Emacs
command execution.
expression with the minibuffer and evaluating it.
The @kbd{r} command is useful when the debugger was invoked due to exit
-from a Lisp call frame (as requested with @kbd{b}); then the value
-specified in the @kbd{r} command is used as the value of that frame. It
-is also useful if you call @code{debug} and use its return value.
-Otherwise, @kbd{r} has the same effect as @kbd{c}, and the specified
-return value does not matter.
+from a Lisp call frame (as requested with @kbd{b} or by entering the
+frame with @kbd{d}); then the value specified in the @kbd{r} command is
+used as the value of that frame. It is also useful if you call
+@code{debug} and use its return value. Otherwise, @kbd{r} has the same
+effect as @kbd{c}, and the specified return value does not matter.
You can't use @kbd{r} when the debugger was entered due to an error.
@end table
@end smallexample
@item exit
-When the first argument is @code{exit}, it indicates the exit of a
-stack frame previously marked to invoke the debugger on exit. The
-second argument given to @code{debug} in this case is the value being
-returned from the frame. The debugger displays @samp{Return value:} on
-the top line of the buffer, followed by the value being returned.
+When the first argument is @code{exit}, it indicates the exit of a stack
+frame previously marked to invoke the debugger on exit. The second
+argument given to @code{debug} in this case is the value being returned
+from the frame. The debugger displays @samp{Return value:} in the top
+line of the buffer, followed by the value being returned.
@item error
@cindex @code{error} in debug
information for future debugger invocations during the same command
invocation.
-The advantage, for the debugger, of using this variable rather than
-another global variable is that the data will never carry over to a
+The advantage, for the debugger, of using this variable rather than an
+ordinary global variable is that the data will never carry over to a
subsequent command invocation.
@end defvar
way to be sure of this except by studying the program, but often the
existing indentation is a clue to where the parentheses should have
been. The easiest way to use this clue is to reindent with @kbd{C-M-q}
-and see what moves.
+and see what moves. @strong{But don't do this yet!} Keep reading,
+first.
Before you do this, make sure the defun has enough close parentheses.
Otherwise, @kbd{C-M-q} will get an error, or will reindent all the rest
insertion of the open parenthesis, and finally return to the mark.)
Then find the actual matching close parenthesis by typing @kbd{C-M-f}
-at the beginning of the defun. This will leave you somewhere short of
+at the beginning of that defun. This will leave you somewhere short of
the place where the defun ought to end. It is possible that you will
find a spurious close parenthesis in that vicinity.
@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/display
-@node Display, Calendar, System Interface, Top
+@node Display, Calendar, Processes, Top
@chapter Emacs Display
This chapter describes a number of features related to the display
@cindex resume (cf. @code{no-redraw-on-reenter})
This variable controls whether Emacs redraws the entire screen after it
has been suspended and resumed. Non-@code{nil} means there is no need
-to redraw, @code{nil} means redrawing is needed.
+to redraw, @code{nil} means redrawing is needed. The default is @code{nil}.
@end defvar
@node Screen Size
one screen line. The additional screen lines used to display a long
text line are called @dfn{continuation} lines. Normally, a @samp{$} in
the rightmost column of the window indicates truncation; a @samp{\} on
-the rightmost column indicates a line that ``wraps'' or is continued
-onto the next line. (The display table can specify alternative
-indicators; see @ref{Display Tables}.)
+the rightmost column indicates a line that ``wraps'' onto the next line,
+which is also called @dfn{continuing} the line. (The display table can
+specify alternative indicators; see @ref{Display Tables}.)
Note that continuation is different from filling; continuation happens
on the screen only, not in the buffer contents, and it breaks a line
@defopt default-truncate-lines
This variable is the default value for @code{truncate-lines}, for
-buffers that do not have local values for it.
+buffers that do not have buffer-local values for it.
@end defopt
@defopt truncate-partial-width-windows
Turning on the cache slows down processing of short lines somewhat.
-This variable is automatically local in every buffer.
+This variable is automatically buffer-local in every buffer.
@end defvar
@node The Echo Area
echo area, or @code{nil} if there is none.
@end defun
+@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
+appears at the end of the message. Otherwise, the cursor appears at
+point---not in the echo area at all.
+
+The value is normally @code{nil}; Lisp programs bind it to @code{t}
+for brief periods of time.
+@end defvar
+
@tindex echo-area-clear-hook
@defvar echo-area-clear-hook
This normal hook is run whenever the echo area is cleared---either by
If the value is zero, then command input is not echoed.
@end defvar
-@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
-appears at the end of the message. Otherwise, the cursor appears at
-point---not in the echo area at all.
-
-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
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.
+@code{invisible} property works.
More generally, you can use the variable @code{buffer-invisibility-spec}
to control which values of the @code{invisible} property make text
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:
+Each element of the list specifies a criterion for invisibility; if a
+character's @code{invisible} property fits any one of these criteria,
+the character is invisible. The list can have two kinds of elements:
@table @code
@item @var{atom}
-A character is invisible if its @code{invisible} propery value
+A character is invisible if its @code{invisible} property 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
+A character is invisible if its @code{invisible} property 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.
property:
@example
-;; If we want to display an ellipsis:
+;; @r{If you want to display an ellipsis:}
(add-to-invisibility-spec '(my-symbol . t))
-;; If you don't want ellipsis:
+;; @r{If you don't want ellipsis:}
(add-to-invisibility-spec 'my-symbol)
(overlay-put (make-overlay beginning end)
'invisible 'my-symbol)
-;; When done with the overlays:
+;; @r{When done with the overlays:}
(remove-from-invisibility-spec '(my-symbol . t))
-;; Or respectively:
+;; @r{Or respectively:}
(remove-from-invisibility-spec 'my-symbol)
@end example
@section Selective Display
@cindex selective display
- @dfn{Selective display} is a pair of features that hide certain
-lines on the screen.
+ @dfn{Selective display} refers to a pair of related features for
+hiding certain lines on the screen.
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 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.
+a Lisp program: it controls which lines are hidden by altering the text.
+The invisible text feature (@pxref{Invisible Text}) has partially
+replaced this feature.
In the second variant, the choice of lines to hide is made
automatically based on indentation. This variant is designed to be a
@itemize @bullet
@item
If the value of @code{selective-display} is @code{t}, then any portion
-of a line that follows a control-m is not displayed.
+of a line that follows a control-m is not displayed. This is explicit
+selective display.
@item
If the value of @code{selective-display} is a positive integer, then
@c now. Is it?
@end defvar
- You can do the same job by creating an overlay with a
+ You can do a similar 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.
+ Temporary displays are used by Lisp programs to put output into a
+buffer and then present it to the user for perusal rather than for
+editing. Many help commands use this feature.
@defspec with-output-to-temp-buffer buffer-name forms@dots{}
This function executes @var{forms} while arranging to insert any
If this variable is non-@code{nil}, @code{with-output-to-temp-buffer}
calls it as a function to do the job of displaying a help buffer. The
function gets one argument, which is the buffer it should display.
-
-In Emacs versions 18 and earlier, this variable was called
-@code{temp-buffer-show-hook}.
@end defvar
@defun momentary-string-display string position &optional char message
The return value of @code{momentary-string-display} is not meaningful.
If the string @var{string} does not contain control characters, you can
-do the same job in a more general way by creating an overlay with a
-@code{before-string} property. @xref{Overlay Properties}.
+do the same job in a more general way by creating (and then subsequently
+deleting) an overlay with a @code{before-string} property.
+@xref{Overlay Properties}.
If @var{message} is non-@code{nil}, it is displayed in the echo area
while @var{string} is displayed in the buffer. If it is @code{nil}, a
and strings preserves text properties, but does not try to preserve
overlays. Changing a buffer's text properties marks the buffer as
modified, while moving an overlay or changing its properties does not.
-Unlike text propery changes, overlay changes are not recorded in the
+Unlike text property changes, overlay changes are not recorded in the
buffer's undo list.
@table @code
if it ever becomes empty (i.e., if it spans no characters).
@item local-map
-@cindex keymap of character
-@kindex local-map @r{(text property)}
+@cindex keymap of character (and overlays)
+@kindex local-map @r{(overlay property)}
If this property is non-@code{nil}, it specifies a keymap for a portion
of the text. The property's value replaces the buffer's local map, when
the character after point is within the overlay. @xref{Active Keymaps}.
@section Width
Since not all characters have the same width, these functions let you
-check the width of a character. @ref{Primitive Indent}
-
-@xref{Screen Lines}, for related
-functions.
+check the width of a character. @xref{Primitive Indent}, and
+@ref{Screen Lines}, for related functions.
@tindex char-width
@defun char-width char
control the display of text on the screen.
@cindex face id
-Each face has its own @dfn{face id number} which distinguishes faces at
+Each face has its own @dfn{face number}, which distinguishes faces at
low levels within Emacs. However, for most purposes, you can refer to
faces in Lisp programs by their names.
@menu
* Standard Faces:: The faces Emacs normally comes with.
+* Defining Faces:: How to define a face with @code{defface}.
* Merging Faces:: How Emacs decides which face to use for a character.
* Face Functions:: How to define and examine faces.
@end menu
one.
@end table
+@node Defining Faces
+@section Defining Faces
+
+ The way to define a new face is with @code{defface}. This creates a
+kind of customization item (@pxref{Customization}) which the user can
+customize using the Customization buffer (@pxref{Easy Customization,,,
+emacs, The GNU Emacs Manual}).
+
+@tindex defface
+@defmac defface face spec doc [keyword value]...
+Declare @var{face} as a customizable face that defaults according to
+@var{spec}. Do not quote the symbol @var{face}. The argument @var{doc}
+specifies the face documentation.
+
+When @code{defface} executes, it defines the face according to
+@var{spec}, then uses any customizations saved in the @file{.emacs} file
+to override that specification.
+
+The purpose of @var{spec} is to specify how the face should appear on
+different kinds of terminals. It should be an alist whose elements have
+the form @code{(@var{display} @var{atts})}. The element's @sc{car},
+@var{display}, specifies a class of terminals. The @sc{cdr},
+@var{atts}, is a list of face attributes and their values; it specifies
+what the face should look like on that kind of terminal. The possible
+attributes are defined in the value of @code{custom-face-attributes}.
+
+The @var{display} part of an element of @var{spec} determines which
+frames the element applies to. If more than one element of @var{spec}
+matches a given frame, the first matching element is the only one used
+for that frame. There are two possibilities for @var{display}:
+
+@table @asis
+@item @code{t}
+This element of @var{spec} matches all frames. Therefore, any
+subsequent elements of @var{spec} are never used. Normally
+@code{t} is used in the last (or only) element of @var{spec}.
+
+@item an list
+If @var{display} is alist, each elements should have the form
+@code{(@var{characteristic} @var{value}@dots{})}. Here
+@var{characteristic} specifies a way of classifying frames, and the
+@var{value}s are possible classifications which @var{display} should
+apply to. Here are the possible values of @var{characteristic}:
+
+@table @code
+@item type
+The kind of window system the frame uses---either @code{x}, @code{pc}
+(for the MS-DOS console), @code{w32} (for MS Windows 9X/NT), or
+@code{tty}.
+
+@item class
+What kinds of colors the frame supports---either @code{color},
+@code{grayscale}, or @code{mono}.
+
+@item background
+The kind of background--- either @code{light} or @code{dark}.
+@end table
+
+If an element of @var{display} specifies more than one @var{value} for a
+given @var{characteristic}, any of those values is acceptable. If
+@var{display} has more than one element, each element should specify a
+different @var{characteristic}; then @emph{each} characteristic of the
+frame must match one of the @var{value}s specified for it in
+@var{display}.
+@end table
+@end defmac
+
+ Here's how the standard face @code{region} could be defined
+with @code{defface}:
+
+@example
+(defface region
+ ((((class color) (background dark))
+ (:background "blue"))
+ (t (:background "gray")))
+ "Used for displaying the region.")
+@end example
+
+ Internally, @code{defface} uses the symbol property
+@code{face-defface-spec} to record the face attributes specified in
+@code{defface}, @code{saved-face} for the attributes saved by the user
+with the customization buffer, and @code{face-documentation} for the
+documentation string.
+
@node Merging Faces
@subsection Merging Faces for Display
@itemize @bullet
@item
-With defaults. Each frame has a @dfn{default face}, whose id number is
-zero, which is used for all text that doesn't somehow specify another
-face.
+With defaults. Each frame has a @dfn{default face}, which is used for
+all text that doesn't somehow specify another face. (We may change this
+in a forthcoming Emacs version to serve as a default for all text.)
@item
With text properties. A character may have a @code{face} property; if so,
highlighted with a particular face (see @code{region-face}, below).
@item
-With special glyphs. Each glyph can specify a particular face id
+With special glyphs. Each glyph can specify a particular face
number. @xref{Glyphs}.
@end itemize
that you specified is always used.
@end defun
-@defun set-face-underline-p face underline-p &optional frame
-This function sets the underline attribute of face @var{face}.
-Non-@code{nil} means do underline; @code{nil} means don't.
-@end defun
-
@tindex set-face-bold-p
@defun set-face-bold-p face bold-p &optional frame
This function sets the bold attribute of face @var{face}.
Non-@code{nil} means italic; @code{nil} means non-italic.
@end defun
+@defun set-face-underline-p face underline-p &optional frame
+This function sets the underline attribute of face @var{face}.
+Non-@code{nil} means do underline; @code{nil} means don't.
+@end defun
+
@defun invert-face face &optional frame
Swap the foreground and background colors of face @var{face}. If the
face doesn't specify both foreground and background, then its foreground
This function returns the name of the font of face @var{face}.
@end defun
-@defun face-underline-p face &optional frame
-This function returns the underline attribute of face @var{face}.
-@end defun
-
@tindex face-bold-p
@defun face-bold-p face &optional frame
This function returns the bold attribute of face @var{face}.
This function returns the italic attribute of face @var{face}.
@end defun
+@defun face-underline-p face &optional frame
+This function returns the underline attribute of face @var{face}.
+@end defun
+
@defun face-id face
-This function returns the face id number of face @var{face}.
+This function returns the face number of face @var{face}.
@end defun
@tindex face-documentation
@end defun
@defvar region-face
-This variable's value specifies the face id to use to display characters
+This variable's value specifies the face number to use to display characters
in the region when it is active (in Transient Mark mode only). The face
thus specified takes precedence over all faces that come from text
properties and overlays, for characters in the region. @xref{The Mark},
for more information about Transient Mark mode.
-Normally, the value is the id number of the face named @code{region}.
+Normally, the value is the face number of the face named @code{region}.
@end defvar
@node Blinking
This section describes the mechanism by which Emacs shows a matching
open parenthesis when the user inserts a close parenthesis.
-@vindex blink-paren-hook
@defvar blink-paren-function
The value of this variable should be a function (of no arguments) to
be called whenever a character with close parenthesis syntax is inserted.
The value of @code{blink-paren-function} may be @code{nil}, in which
case nothing is done.
-
-@quotation
-@strong{Please note:} This variable was named @code{blink-paren-hook} in
-older Emacs versions, but since it is not called with the standard
-convention for hooks, it was renamed to @code{blink-paren-function} in
-version 19.
-@end quotation
@end defvar
@defvar blink-matching-paren
Otherwise, mode lines are displayed normally, just like text. The
default is @code{t}.
-For X window frames, this displays mode lines using the face named
+For window frames, this displays mode lines using the face named
@code{modeline}, which is normally the inverse of the default face
unless you change it.
@end defopt
@item
Character codes 128 through 255 map to sequences of four glyphs, where
the first glyph is the @sc{ASCII} code for @samp{\}, and the others are
-digit characters representing the code in octal. (A display table can
-specify a glyph to use instead of @samp{\}.)
+digit characters representing the charatcer code in octal. (A display
+table can specify a glyph to use instead of @samp{\}.)
+
+@item
+Multibyte character codes above 256 are displayed as themselves, or as a
+question mark or empty box if the terminal cannot display that
+character.
@end itemize
The usual display conventions apply even when there is a display
table, for any character whose entry in the active display table is
@code{nil}. Thus, when you set up a display table, you need only
-specify the characters for which you want unusual behavior.
+specify the characters for which you want special behavior.
These variables affect the way certain characters are displayed on the
screen. Since they change the number of columns the characters occupy,
@section Display Tables
@cindex display table
-You can use the @dfn{display table} feature to control how all 256
-possible character codes display on the screen. This is useful for
-displaying European languages that have letters not in the @sc{ASCII}
-character set.
+You can use the @dfn{display table} feature to control how all possible
+character codes display on the screen. This is useful for displaying
+European languages that have letters not in the @sc{ASCII} character
+set.
The display table maps each character code into a sequence of
@dfn{glyphs}, each glyph being an image that takes up one character
characters, the whole buffer will be displayed as one long ``line.''
The display table also has six ``extra slots'' which serve special
-purposes. Here is a table of their meanings; @code{nil} means to use
-the default stated below.
+purposes. Here is a table of their meanings; @code{nil} in any slot
+means to use the default for that slot, as stated below.
@table @asis
@item 0
@end defun
@defvar buffer-display-table
-This variable is automatically local in all buffers; its value in a
-particular buffer is the display table for that buffer, or @code{nil} if
-the buffer does not have an assigned display table.
+This variable is automatically buffer-local in all buffers; its value in
+a particular buffer specifies the display table for that buffer. If it
+is @code{nil}, that means the buffer does not have an assigned display
+table.
@end defvar
@defvar standard-display-table
@item string
Send the characters in @var{string} to the terminal to output
this glyph. This alternative is available on character terminals,
-but not under X.
+but not under a window system.
@item integer
-Define this glyph code as an alias for code @var{integer}. You can use
-an alias to specify a face code for the glyph; see below.
+Define this glyph code as an alias for glyph code @var{integer}. You
+can use an alias to specify a face code for the glyph; see below.
@item @code{nil}
-This glyph is simple. On an ordinary terminal, the glyph code mod 524288
-is the character to output. With X, the glyph code mod 524288 is the
-character to output, and the glyph code divided by 524288 specifies the
-@dfn{face id number} to use while outputting it. (524288 is
+This glyph is simple. On an ordinary terminal, the glyph code mod
+524288 is the character to output. In a window system, the glyph code
+mod 524288 is the character to output, and the glyph code divided by
+524288 specifies the face number (@pxref{Face Functions}) to use while
+outputting it. (524288 is
@ifinfo
-2**19.
+2**19.)
@end ifinfo
@tex
-$2^{19}$.
+$2^{19}$.)
@end tex
@xref{Faces}.
@end table
@defvar visible-bell
This variable determines whether Emacs should flash the screen to
represent a bell. Non-@code{nil} means yes, @code{nil} means no. This
-is effective under X windows, and on a character-only terminal provided
-the terminal's Termcap entry defines the visible bell capability
-(@samp{vb}).
+is effective on a window system, and on a character-only terminal
+provided the terminal's Termcap entry defines the visible bell
+capability (@samp{vb}).
@end defvar
@tindex ring-bell-function
@comment -*-texinfo-*-
+@c This is part of the GNU Emacs Lisp Reference Manual.
+@c Copyright (C) 1992, 1993, 1994, 1998 Free Software Foundation, Inc.
+@c See the file elisp.texi for copying conditions.
-@c This file is intended to be used as a section within the Emacs Lisp
-@c Reference Manual. It may also be used by an independent Edebug User
-@c Manual, edebug.tex, in which case the Edebug node below should be used
+@c This file can also be used by an independent Edebug User
+@c Manual in which case the Edebug node below should be used
@c with the following links to the Bugs section and to the top level:
@c , Bugs and Todo List, Top, Top
edebug-all-defs} toggles the value of the variable
@code{edebug-all-defs}.
-@findex edebug-all-forms
-@findex eval-region (Edebug)
-@findex eval-current-buffer (Edebug)
+@findex eval-region @r{(Edebug)}
+@findex eval-current-buffer @r{(Edebug)}
If @code{edebug-all-defs} is non-@code{nil}, then the commands
@code{eval-region}, @code{eval-current-buffer}, and @code{eval-buffer}
also instrument any definitions they evaluate. Similarly,
edebug-all-forms} toggles this option.
@findex edebug-eval-top-level-form
-Another command, @kbd{M-x edebug-eval-top-level-form}, is available to
+ Another command, @kbd{M-x edebug-eval-top-level-form}, is available to
instrument any top-level form regardless of the values of
@code{edebug-all-defs} and @code{edebug-all-forms}.
-When Edebug is about to instrument code for the first time in a session,
-it runs the hook @code{edebug-setup-hook}, then sets it to @code{nil}.
-You can use this to load up Edebug specifications associated with a
-package you are using, but only when you also use Edebug.
-
-While Edebug is active, the command @kbd{I}
+ While Edebug is active, the command @kbd{I}
(@code{edebug-instrument-callee}) instruments the definition of the
function or macro called by the list form after point, if is not already
instrumented. This is possible only if Edebug knows where to find the
@cindex interactive commands (Edebug)
@cindex anonymous lambda expressions (Edebug)
@cindex Common Lisp (Edebug)
-@pindex cl.el (Edebug)
+@pindex cl.el @r{(Edebug)}
@pindex cl-specs.el
Edebug knows how to instrument all the standard special forms, an
interactive form with an expression argument, anonymous lambda
user-defined macro will do with the arguments of a macro call, so you
must tell it; @xref{Instrumenting Macro Calls}, for details.
-@findex eval-expression (Edebug)
+ When Edebug is about to instrument code for the first time in a
+session, it runs the hook @code{edebug-setup-hook}, then sets it to
+@code{nil}. You can use this to arrange to load Edebug specifications
+(@pxref{Instrumenting Macro Calls}) associated with a package you are
+using, but actually load them only if you use Edebug.
+
+@findex eval-expression @r{(Edebug)}
To remove instrumentation from a definition, simply reevaluate its
definition in a way that does not instrument. There are two ways of
evaluating forms that never instrument them: from a file with
the previous condition expression in the minibuffer so you can edit it.
You can make a conditional or unconditional breakpoint
-@dfn{temporary} by using a prefix arg with the command to set the
+@dfn{temporary} by using a prefix argument with the command to set the
breakpoint. When a temporary breakpoint stops the program, it is
automatically unset.
evaluating the condition gets an error, execution does not stop.
@findex edebug-set-global-break-condition
-@vindex edebug-global-break-condition
The condition expression is stored in
@code{edebug-global-break-condition}. You can specify a new expression
using the @kbd{X} command (@code{edebug-set-global-break-condition}).
1))
@end example
-When the @code{fac} definition is instrumented and the function is
+ When the @code{fac} definition is instrumented and the function is
called, the call to @code{edebug} acts as a breakpoint. Depending on
the execution mode, Edebug stops or pauses there.
-If no instrumented code is being executed when @code{edebug} is called,
+ If no instrumented code is being executed when @code{edebug} is called,
that function calls @code{debug}.
@c This may not be a good idea anymore.
@node Trapping Errors
@subsection Trapping Errors
-Emacs normally displays an error message when an error is signaled and
-not handled with @code{condition-case}. While Edebug is active, it
-normally responds to all unhandled errors. You can customize this with
-the options @code{edebug-on-error} and @code{edebug-on-quit}; see
-@ref{Edebug Options}.
+ Emacs normally displays an error message when an error is signaled and
+not handled with @code{condition-case}. While Edebug is active and
+executing instrumented code, it normally responds to all unhandled
+errors. You can customize this with the options @code{edebug-on-error}
+and @code{edebug-on-quit}; see @ref{Edebug Options}.
-When Edebug responds to an error, it shows the last stop point
+ When Edebug responds to an error, it shows the last stop point
encountered before the error. This may be the location of a call to a
function which was not instrumented, within which the error actually
occurred. For an unbound variable error, the last known stop point
case you might want to display a full backtrace (@pxref{Edebug Misc}).
@c Edebug should be changed for the following: -- dan
-If you change @code{debug-on-error} or @code{debug-on-quit} while
+ If you change @code{debug-on-error} or @code{debug-on-quit} while
Edebug is active, these changes will be forgotten when Edebug becomes
inactive. Furthermore, during Edebug's recursive edit, these variables
are bound to the values they had outside of Edebug.
@node Edebug Views
@subsection Edebug Views
-These Edebug commands let you view aspects of the buffer and window
+ These Edebug commands let you view aspects of the buffer and window
status that obtained before entry to Edebug. The outside window
configuration is the collection of windows and contents that were in
effect outside of Edebug.
source code buffer, you must use @kbd{C-x X W} from the global keymap.
@end table
-You can view the outside window configuration with @kbd{v} or just
+ You can view the outside window configuration with @kbd{v} or just
bounce to the point in the current buffer with @kbd{p}, even if
it is not normally displayed. After moving point, you may wish to jump
back to the stop point with @kbd{w} from a source code buffer.
-Each time you use @kbd{W} to turn saving @emph{off}, Edebug forgets the
+ Each time you use @kbd{W} to turn saving @emph{off}, Edebug forgets the
saved outside window configuration---so that even if you turn saving
back @emph{on}, the current window configuration remains unchanged when
you next exit Edebug (by continuing the program). However, the
@node Edebug Eval
@subsection Evaluation
-While within Edebug, you can evaluate expressions ``as if'' Edebug were
+ While within Edebug, you can evaluate expressions ``as if'' Edebug were
not running. Edebug tries to be invisible to the expression's
evaluation and printing. Evaluation of expressions that cause side
effects will work as expected except for things that Edebug explicitly
@end table
@cindex lexical binding (Edebug)
-Edebug supports evaluation of expressions containing references to
+ Edebug supports evaluation of expressions containing references to
lexically bound symbols created by the following constructs in
@file{cl.el} (version 2.03 or later): @code{lexical-let},
@code{macrolet}, and @code{symbol-macrolet}.
-
@node Eval List
@subsection Evaluation List Buffer
-You can use the @dfn{evaluation list buffer}, called @samp{*edebug*}, to
+ You can use the @dfn{evaluation list buffer}, called @samp{*edebug*}, to
evaluate expressions interactively. You can also set up the
@dfn{evaluation list} of expressions to be evaluated automatically each
time Edebug updates the display.
(@code{edebug-visit-eval-list}).
@end table
-In the @samp{*edebug*} buffer you can use the commands of Lisp
+ In the @samp{*edebug*} buffer you can use the commands of Lisp
Interaction mode (@pxref{Lisp Interaction,,, emacs, The GNU Emacs
Manual}) as well as these special commands:
@table @kbd
-@item LFD
+@item C-j
Evaluate the expression before point, in the outside context, and insert
the value in the buffer (@code{edebug-eval-print-last-sexp}).
(@code{edebug-where}).
@end table
-You can evaluate expressions in the evaluation list window with
-@kbd{LFD} or @kbd{C-x C-e}, just as you would in @samp{*scratch*};
+ You can evaluate expressions in the evaluation list window with
+@kbd{C-j} or @kbd{C-x C-e}, just as you would in @samp{*scratch*};
but they are evaluated in the context outside of Edebug.
-The expressions you enter interactively (and their results) are lost
+ The expressions you enter interactively (and their results) are lost
when you continue execution; but you can set up an @dfn{evaluation list}
consisting of expressions to be evaluated each time execution stops.
@cindex evaluation list group
-To do this, write one or more @dfn{evaluation list groups} in the
+ To do this, write one or more @dfn{evaluation list groups} in the
evaluation list buffer. An evaluation list group consists of one or
more Lisp expressions. Groups are separated by comment lines.
-The command @kbd{C-c C-u} (@code{edebug-update-eval-list}) rebuilds the
+ The command @kbd{C-c C-u} (@code{edebug-update-eval-list}) rebuilds the
evaluation list, scanning the buffer and using the first expression of
each group. (The idea is that the second expression of the group is the
value previously computed and displayed.)
-Be careful not to add expressions that execute instrumented code since
-that would cause an infinite loop.
-@c There ought to be a way to fix this.
-
-Each entry to Edebug redisplays the evaluation list by inserting each
+ Each entry to Edebug redisplays the evaluation list by inserting each
expression in the buffer, followed by its current value. It also
inserts comment lines so that each expression becomes its own group.
Thus, if you type @kbd{C-c C-u} again without changing the buffer text,
the evaluation list is effectively unchanged.
-If an error occurs during an evaluation from the evaluation list, the
+ If an error occurs during an evaluation from the evaluation list, the
error message is displayed in a string as if it were the result.
Therefore, expressions that use variables not currently valid do not
interrupt your debugging.
-Here is an example of what the evaluation list window looks like after
+ Here is an example of what the evaluation list window looks like after
several expressions have been added to it:
@smallexample
If an expression in your program produces a value containing circular
list structure, you may get an error when Edebug attempts to print it.
-@vindex edebug-print-length
-@vindex edebug-print-level
One way to cope with circular structure is to set @code{print-length}
or @code{print-level} to truncate the printing. Edebug does this for
you; it binds @code{print-length} and @code{print-level} to 50 if they
and @code{edebug-print-level} specify the values to use within Edebug.)
@xref{Output Variables}.
+@defopt edebug-print-length
+If non-@code{nil}, bind @code{print-length} to this while printing
+results in Edebug. The default value is @code{50}.
+@xref{Printing in Edebug}.
+@end defopt
+
+@defopt edebug-print-level
+If non-@code{nil}, bind @code{print-level} to this while printing
+results in Edebug. The default value is @code{50}.
+@end defopt
+
You can also print circular structures and structures that share
elements more informatively by using the @file{cust-print} package.
structure. This notation is used for any shared elements of lists or
vectors.
+@defopt edebug-print-circle
+If non-@code{nil}, bind @code{print-circle} to this while printing
+results in Edebug. The default value is @code{nil}.
+@end defopt
+
Other programs can also use custom printing; see @file{cust-print.el}
for details.
frequency. All execution of an instrumented function accumulates
frequency counts, both before and after evaluation of each instrumented
expression, even if the execution mode is Go-nonstop. Coverage testing
-is more expensive, so it is only done if @code{edebug-test-coverage} is
+is more expensive, so it is done only if @code{edebug-test-coverage} is
non-@code{nil}. The command @kbd{M-x edebug-display-freq-count}
displays both the frequency data and the coverage data (if recorded).
This command displays the frequency count data for each line of the
current definition.
-The frequency counts appear as comment lines after each line of code, and
-you can undo all insertions with one @code{undo} command. The counts
-appear under the @kbd{(} before an expression or the @kbd{)} after
-an expression, or on the last character of a symbol. Values do not appear if
-they are equal to the previous count on the same line.
+The frequency counts appear as comment lines after each line of code,
+and you can undo all insertions with one @code{undo} command. The
+counts appear under the @samp{(} before an expression or the @samp{)}
+after an expression, or on the last character of a symbol. Values do
+not appear if they are equal to the previous count on the same line.
The character @samp{=} following the count for an expression says that
the expression has returned the same value each time it was evaluated
@node Instrumenting Macro Calls
@subsection Instrumenting Macro Calls
-When Edebug instruments an expression that calls a Lisp macro, it needs
-additional advice to do the job properly. This is because there is no
-way to tell which subexpressions of the macro call are forms to be
-evaluated. (Evaluation may occur explicitly in the macro body, or when
-the resulting expansion is evaluated, or any time later.) You must
-explain the format of calls to each macro to enable Edebug to handle it.
-To do this, use @code{def-edebug-spec} to define the format of
-calls to a given macro.
+ When Edebug instruments an expression that calls a Lisp macro, it needs
+additional information about the macro to do the job properly. This is
+because there is no a-priori way to tell which subexpressions of the
+macro call are forms to be evaluated. (Evaluation may occur explicitly
+in the macro body, or when the resulting expansion is evaluated, or any
+time later.)
+
+ Therefore, you must define an Edebug specification for each macro that
+Edebug will encounter, to explain the format of calls to that macro. To
+do this, use @code{def-edebug-spec}.
@deffn Macro def-edebug-spec macro specification
Specify which expressions of a call to macro @var{macro} are forms to be
similar to the formal argument list of the macro definition, but
specifications are much more general than macro arguments.
-The @var{macro} argument may actually be any symbol, not just a macro
+The @var{macro} argument can actually be any symbol, not just a macro
name.
@end deffn
A specification list may contain sublists which match arguments that are
themselves lists, or it may contain vectors used for grouping. Sublists
and groups thus subdivide the specification list into a hierarchy of
-levels. Specification keywords only apply to the remainder of the
+levels. Specification keywords apply only to the remainder of the
sublist or group they are contained in.
When a specification list involves alternatives or repetition, matching
@c Need to document extensions with &symbol and :symbol
-Here is a list of additional specifications that may only appear after
+Here is a list of additional specifications that may appear only after
@code{&define}. See the @code{defun} example below.
@table @code
@end table
@node Backtracking
-@subsubsection Backtracking
+@subsubsection Backtracking in Specifications
@cindex backtracking
@cindex syntax error (Edebug)
@end defopt
@defopt edebug-trace
-@findex edebug-print-trace-before
-@findex edebug-print-trace-after
Non-@code{nil} means display a trace of function entry and exit.
Tracing output is displayed in a buffer named @samp{*edebug-trace*}, one
function entry or exit per line, indented by the recursion level.
@xref{Edebug Execution Modes}.
@end defopt
-@defopt edebug-print-length
-If non-@code{nil}, bind @code{print-length} to this while printing
-results in Edebug. The default value is @code{50}.
-@xref{Printing in Edebug}.
-@end defopt
-
-@defopt edebug-print-level
-If non-@code{nil}, bind @code{print-level} to this while printing
-results in Edebug. The default value is @code{50}.
-@end defopt
-
-@defopt edebug-print-circle
-If non-@code{nil}, bind @code{print-circle} to this while printing
-results in Edebug. The default value is @code{nil}.
-@end defopt
-
@defopt edebug-on-error
Edebug binds @code{debug-on-error} to this value, if
@code{debug-on-error} was previously @code{nil}. @xref{Trapping
@xref{Read Only Buffers}.
@item cyclic-function-indirection
-@code{"Symbol's chain of function indirections contains a@*
-loop"}@*
+@code{"Symbol's chain of function indirections contains a loop"}@*
@xref{Function Indirection}.
@item end-of-buffer
@item end-of-file
@code{"End of file during parsing"}@*
-This is not a @code{file-error}.@*
+Note that this is not a @code{file-error}
+because it pertains to the Lisp reader, not to file I/O.
@xref{Input Functions}.
+@item file-already-exists
+This is a @code{file-error}.@*
+@xref{Writing to Files}.
+
@item file-date-error
This is a subcategory of @code{file-error}. It occurs when
@code{copy-file} tries and fails to set the last-modification time of
This is a @code{file-error}.@*
@xref{File Locks}.
-@item file-already-exists
-This is a @code{file-error}.@*
-@xref{Writing to Files}.
-
@item file-supersession
This is a @code{file-error}.@*
@xref{Modification Time}.
@code{"Invalid regexp"}@*
@xref{Regular Expressions}.
+@item mark-inactive
+@code{Mark inactive"}@*
+@xref{The Mark}.
+
@item no-catch
@code{"No catch for tag"}@*
@xref{Catch and Throw}.
+@item scan-error
+@code{"Scan error"}@*
+This happens when certain syntax-parsing functions
+find invalid syntax or mismatched parentheses.@*
+@xref{List Motion}, and @ref{Parsing Expressions}.
+
@item search-failed
@code{"Search failed"}@*
@xref{Searching and Matching}.
@item setting-constant
@code{"Attempt to set a constant symbol"}@*
-The values of the symbols @code{nil} and @code{t}
+The values of the symbols @code{nil} and @code{t},
+and any symbols that start with @samp{:},
may not be changed.@*
@xref{Constant Variables, , Variables that Never Change}.
@xref{Type Predicates}.
@end table
- These error types, which are all classified as special cases of
+ These kinds of error, which are classified as special cases of
@code{arith-error}, can occur on certain systems for invalid use of
mathematical functions.
@example
@group
-'123 ; @r{An object, shown without evaluation.}
+'123 ; @r{A number, shown without evaluation.}
@result{} 123
@end group
@group
always @code{t}; you cannot set or bind them to any other values. Thus,
these two symbols act like self-evaluating forms, even though
@code{eval} treats them like any other symbol. A symbol whose name
-starts with @samp{:} also self-evaluates in the same way.
+starts with @samp{:} also self-evaluates in the same way; likewise,
+its value ordinarily cannot be changed. @xref{Constant Variables}.
@node Classifying Lists
@subsection Classification of List Forms
@defvar max-lisp-eval-depth
This variable defines the maximum depth allowed in calls to @code{eval},
@code{apply}, and @code{funcall} before an error is signaled (with error
-message @code{"Lisp nesting exceeds max-lisp-eval-depth"}). This counts
-internal uses of those functions, such as for calling the functions
-mentioned in Lisp expressions, and recursive evaluation of function call
-arguments and function body forms.
-
-This limit, with the associated error when it is exceeded, is one way
-that Lisp avoids infinite recursion on an ill-defined function.
+message @code{"Lisp nesting exceeds max-lisp-eval-depth"}). This limit,
+with the associated error when it is exceeded, is one way that Lisp
+avoids infinite recursion on an ill-defined function.
@cindex Lisp nesting error
+The depth limit counts internal uses of @code{eval}, @code{apply}, and
+@code{funcall}, such as for calling the functions mentioned in Lisp
+expressions, and recursive evaluation of function call arguments and
+function body forms, as well as explicit calls in Lisp code.
+
The default value of this variable is 200. If you set it to a value
less than 100, Lisp will reset it to 100 if the given value is reached.
* 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
@node Visiting Files
the user whether to reread the changed file. If the user says
@samp{yes}, any changes previously made in the buffer are lost.
-If @code{find-file-noselect} needs to create a buffer, and there is no
-file named @var{filename}, it displays the message @samp{New file} in
-the echo area, and leaves the buffer empty.
-
This function displays warning or advisory messages in various peculiar
-cases, unless the optional argument @var{nowarn} is non-@code{nil}.
+cases, unless the optional argument @var{nowarn} is non-@code{nil}. For
+example, if it needs to create a buffer, and there is no file named
+@var{filename}, it displays the message @samp{New file} in the echo
+area, and leaves the buffer empty.
The @code{find-file-noselect} function normally calls
@code{after-find-file} after reading the file (@pxref{Subroutines of
The optional @var{exiting} argument, if non-@code{nil}, requests this
function to offer also to save certain other buffers that are not
-visiting files. These are buffers that have a non-@code{nil} local
-value of @code{buffer-offer-save}. (A user who says yes to saving one
-of these is asked to specify a file name to use.) The
+visiting files. These are buffers that have a non-@code{nil}
+buffer-local value of @code{buffer-offer-save}. (A user who says yes to
+saving one of these is asked to specify a file name to use.) The
@code{save-buffers-kill-emacs} function passes a non-@code{nil} value
for this argument.
@end deffn
-@defvar buffer-offer-save
-When this variable is non-@code{nil} in a buffer, Emacs offers to save
-the buffer on exit even if the buffer is not visiting a file. The
-variable is automatically local in all buffers. Normally, Mail mode
-(used for editing outgoing mail) sets this to @code{t}.
-@end defvar
-
@deffn Command write-file filename
This function writes the current buffer into file @var{filename}, makes
the buffer visit that file, and marks it not modified. Then it renames
the buffer based on @var{filename}, appending a string like @samp{<2>}
if necessary to make a unique buffer name. It does most of this work by
-calling @code{set-visited-file-name} and @code{save-buffer}.
+calling @code{set-visited-file-name} (@pxref{Buffer File Name}) and
+@code{save-buffer}.
@end deffn
Saving a buffer runs several hooks. It also performs format
@c Emacs 19 feature
@defvar local-write-file-hooks
This works just like @code{write-file-hooks}, but it is intended to be
-made local to particular buffers, and used for hooks that pertain to the
-file name or the way the buffer contents were obtained.
+made buffer-local in particular buffers, and used for hooks that pertain
+to the file name or the way the buffer contents were obtained.
The variable is marked as a permanent local, so that changing the major
mode does not alter a buffer-local value. This is convenient for
switching to a new major mode always resets this variable. When you use
@code{add-hooks} to add an element to this hook, you should @emph{not}
specify a non-@code{nil} @var{local} argument, since this variable is
-used @emph{only} locally.
+used @emph{only} buffer-locally.
@end defvar
@c Emacs 19 feature
or Copy}. Yet, at the same time, saving a precious file always breaks
all hard links between the file you save and other file names.
-Some modes set this variable non-@code{nil} locally in particular
-buffers.
+Some modes give this variable non-@code{nil} buffer-local value
+in particular buffers.
@end defvar
@defopt require-final-newline
major modes set it to @code{t} in particular buffers.
@end defopt
-@deffn Command set-visited-file-name filename &optional no-query
-This function changes the visited file name of the current buffer to
-@var{filename}. It also renames the buffer based on @var{filename},
-appending a string like @samp{<2>} if necessary to make a unique buffer
-name. It marks the buffer as @emph{modified},a since the contents do not
-(as far as Emacs knows) match the actual file's contents.
-
-If the specified file already exists, @code{set-visited-file-name}
-asks for confirmation unless @var{no-query} is non-@code{nil}.
-@end deffn
+ See also the function @code{set-visited-file-name} (@pxref{Buffer File
+Name}).
@node Reading from Files
@comment node-name, next, previous, up
@tindex with-temp-file
@defmac with-temp-file file body...
-The @code{with-temp-file} macro evaluates the @var{body} forms
-with a temporary buffer as the current buffer; then, at the end, it
-writes the buffer contents into file @var{file}. It kills the temporary
-buffer when finished, restoring the buffer that was current before the
-@code{with-temp-file} form.
-
-The return value is the value of the last form in @var{body}. You can
-return the contents of the temporary buffer by using
-@code{(buffer-string)} as the last form.
+The @code{with-temp-file} macro evaluates the @var{body} forms with a
+temporary buffer as the current buffer; then, at the end, it writes the
+buffer contents into file @var{file}. It kills the temporary buffer
+when finished, restoring the buffer that was current before the
+@code{with-temp-file} form. Then it returns the value of the last form
+in @var{body}.
The current buffer is restored even in case of an abnormal exit via
@code{throw} or error (@pxref{Nonlocal Exits}).
Emacs can then detect the first attempt to modify a buffer visiting a
file that is locked by another Emacs job, and ask the user what to do.
- File locks do not work properly when multiple machines can share
-file systems, such as with NFS. Perhaps a better file locking system
-will be implemented in the future. When file locks do not work, it is
-possible for two users to make changes simultaneously, but Emacs can
-still warn the user who saves second. Also, the detection of
-modification of a buffer visiting a file changed on disk catches some
-cases of simultaneous editing; see @ref{Modification Time}.
+ File locks are not completely reliable when multiple machines can
+share file systems. When file locks do not work, it is possible for two
+users to make changes simultaneously, but Emacs can still warn the user
+who saves second. Also, the detection of modification of a buffer
+visiting a file changed on disk catches some cases of simultaneous
+editing; see @ref{Modification Time}.
@defun file-locked-p filename
This function returns @code{nil} if the file @var{filename} is not
@example
@group
(file-attributes "files.texi")
- @result{} (nil
- 1
- 2235
- 75
+ @result{} (nil 1 2235 75
(8489 20284)
(8489 20284)
(8489 20285)
- 14906
- "-rw-rw-rw-"
- nil
- 129500
- -32252)
+ 14906 "-rw-rw-rw-"
+ nil 129500 -32252)
@end group
@end example
@defvar default-directory
The value of this buffer-local variable is the default directory for the
current buffer. It should be an absolute directory name; it may start
-with @samp{~}. This variable is local in every buffer.
+with @samp{~}. This variable is buffer-local in every buffer.
@code{expand-file-name} uses the default directory when its second
argument is @code{nil}.
@end group
@end example
-If a @samp{~} or a @samp{/} appears following a @samp{/}, after
-substitution, everything before the following @samp{/} is discarded:
+After substitution, if a @samp{~} or a @samp{/} appears following a
+@samp{/}, everything before the following @samp{/} is discarded:
@example
@group
@noindent
@code{add-name-to-file}, @code{copy-file}, @code{delete-directory},
-@code{delete-file},@*
+@code{delete-file},
@code{diff-latest-backup-file},
@code{directory-file-name},
-@code{directory-files},@*
+@code{directory-files},
@code{dired-call-process},
@code{dired-compress-file}, @code{dired-uncache},
-@code{expand-file-name},@*
-@code{file-accessible-directory-p},
-@code{file-attributes}, @code{file-directory-p},@*
-@code{file-executable-p}, @code{file-exists-p}, @code{file-local-copy},
-@code{file-modes}, @code{file-name-all-completions},
-@code{file-name-as-directory}, @code{file-name-completion},@*
+@code{expand-file-name},
+@code{file-accessible-directory-p},@*
+@code{file-attributes},
+@code{file-directory-p},
+@code{file-executable-p}, @code{file-exists-p},@*
+@code{file-local-copy},
+@code{file-modes}, @code{file-name-all-completions},@*
+@code{file-name-as-directory},
+@code{file-name-completion},
@code{file-name-directory},
@code{file-name-nondirectory},
@code{file-name-sans-versions}, @code{file-newer-than-file-p},
@code{file-readable-p}, @code{file-regular-p}, @code{file-symlink-p},
@code{file-truename}, @code{file-writable-p},
@code{find-backup-file-name},
-@code{get-file-buffer},
-@code{insert-directory},@*
+@code{get-file-buffer},@*
+@code{insert-directory},
@code{insert-file-contents},
@code{load}, @code{make-directory},
@code{make-symbolic-link}, @code{rename-file}, @code{set-file-modes},
-@code{set-visited-file-modtime}, @code{shell-command}.
-@code{unhandled-file-name-directory},@*
+@code{set-visited-file-modtime}, @code{shell-command}.@*
+@code{unhandled-file-name-directory},
@code{vc-registered},
-@code{verify-visited-file-modtime}, @code{write-region}.
+@code{verify-visited-file-modtime},@*
+@code{write-region}.
Handlers for @code{insert-file-contents} typically need to clear the
buffer's modified flag, with @code{(set-buffer-modified-p nil)}, if the
this format.
@item from-fn
-A function or shell command to decode data in this format (to convert
+A shell command or function to decode data in this format (to convert
file data into the usual Emacs data representation).
-If @var{from-fn} is a function, it is called with two args, @var{begin}
+A shell command is represented as a string; Emacs runs the command as a
+filter to perform the conversion.
+
+If @var{from-fn} is a function, it is called with two arguments, @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
of the file no longer matches @var{regexp}. Otherwise it is likely to
get called again.
-If @var{from-fn} is a string, it is a shell command; Emacs runs the
-command as a filter to perform the conversion.
-
@item to-fn
-A function or shell command to encode data in this format (to convert
-the usual Emacs data representation into this format).
+A shell command or function to encode data in this format---that is, to
+convert the usual Emacs data representation into this format.
If @var{to-fn} is a string, it is a shell command; Emacs runs the
command as a filter to perform the conversion.
-If @var{to-fn} is a function, it is called with two args, @var{begin}
+If @var{to-fn} is a function, it is called with two arguments, @var{begin}
and @var{end}, which specify the part of the buffer it should convert.
There are two ways it can do the conversion:
@defvar buffer-file-format
This variable states the format of the visited file. More precisely,
this is a list of the file format names that were decoded in the course
-of visiting the current buffer's file. It is always local in all
+of visiting the current buffer's file. It is always buffer-local in all
buffers.
@end defvar
@key{RET} for @var{format} specifies @code{nil}.
@end deffn
-@deffn format-insert-file file format %optional beg end
+@deffn Command format-insert-file file format &optional beg end
This command inserts the contents of file @var{file}, converting it
according to format @var{format}. If @var{beg} and @var{end} are
non-@code{nil}, they specify which part of the file to read, as in
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
-@cindex file types on MS-DOS
-@cindex text files and binary files
-@cindex binary files and text files
-@cindex Windows file types
-
-@c ??? This needs to be updated.
-
- Emacs on MS-DOS and on Windows NT or 95 makes a distinction between
-text files and binary files. This is necessary because ordinary text
-files on MS-DOS use a two character sequence between lines:
-carriage-return and linefeed (@sc{crlf}). Emacs expects just a newline
-character (a linefeed) between lines. When Emacs reads or writes a text
-file on MS-DOS, it needs to convert the line separators. This means it
-needs to know which files are text files and which are binary. It makes
-this decision when visiting a file, and records the decision in the
-variable @code{buffer-file-type} for use when the file is saved.
-
- @xref{MS-DOS Subprocesses}, for a related feature for subprocesses.
-
-@defvar buffer-file-type
-This variable, automatically local in each buffer, records the file type
-of the buffer's visited file. The value is @code{nil} for text,
-@code{t} for binary.
+is always buffer-local in all buffers.
@end defvar
-
-@defun find-buffer-file-type filename
-This function determines whether file @var{filename} is a text file
-or a binary file. It returns @code{nil} for text, @code{t} for binary.
-@end defun
-
-@defopt file-name-buffer-file-type-alist
-This variable holds an alist for distinguishing text files from binary
-files. Each element has the form (@var{regexp} . @var{type}), where
-@var{regexp} is matched against the file name, and @var{type} may be
-@code{nil} for text, @code{t} for binary, or a function to call to
-compute which. If it is a function, then it is called with a single
-argument (the file name) and should return @code{t} or @code{nil}.
-@end defopt
-
-@defopt default-buffer-file-type
-This variable specifies the default file type for files whose names
-don't indicate anything in particular. Its value should be @code{nil}
-for text, or @code{t} for binary.
-@end defopt
-
-@deffn Command find-file-text filename
-Like @code{find-file}, but treat the file as text regardless of its name.
-@end deffn
-
-@deffn Command find-file-binary filename
-Like @code{find-file}, but treat the file as binary regardless of its
-name.
-@end deffn
@dfn{terminal frame}. If you create additional ones, Emacs displays
one and only one at any given time---on the terminal screen, of course.
- When Emacs communicates directly with an X server, 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.
+ When Emacs communicates directly with a supported window system, such
+as X Windows, it does not have a terminal frame; instead, it starts with
+a single @dfn{window frame}, but you can create more, and Emacs can
+display several such frames at once as is usual for window systems.
@defun framep object
This predicate returns @code{t} if @var{object} is a frame, and
@menu
* Creating Frames:: Creating additional frames.
-* Multiple Displays:: Creating frames on other X displays.
+* Multiple Displays:: Creating frames on other displays.
* Frame Parameters:: Controlling frame size, position, font, etc.
* Frame Titles:: Automatic updating of frame titles.
* Deleting Frames:: Frames last until explicitly deleted.
* Minibuffers and Frames:: How a frame finds the minibuffer to use.
* Input Focus:: Specifying the selected frame.
* Visibility of Frames:: Frames may be visible or invisible, or icons.
-* Raising and Lowering:: Raising a frame makes it hide other X windows;
+* Raising and Lowering:: Raising a frame makes it hide other windows;
lowering it makes the others hide them.
* Frame Configurations:: Saving the state of all frames.
* Mouse Tracking:: Getting events that say when the mouse moves.
* Pop-Up Menus:: Displaying a menu for the user to select from.
* Dialog Boxes:: Displaying a box to ask yes or no.
* Pointer Shapes:: Specifying the shape of the mouse pointer.
-* X Selections:: Transferring text to and from other X clients.
+* Window System Selections:: Transferring text to and from other X clients.
* Font Names:: Looking up font names.
* Color Names:: Getting the definitions of color names.
* Resources:: Getting resource values from the server.
To create a new frame, call the function @code{make-frame}.
@defun make-frame &optional alist
-This function creates a new frame. If you are using X, it makes
-an X window frame; otherwise, it makes a terminal frame.
+This function creates a new frame. If you are using a supported window
+system, it makes a 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
variable @code{default-frame-alist}; parameters not specified even there
-default from the standard X defaults file and X resources.
+default from the standard X resources or whatever is used instead on
+your system.
The set of possible parameters depends in principle on what kind of
-window system Emacs uses to display its frames. @xref{X Frame
+window system Emacs uses to display its frames. @xref{Window Frame
Parameters}, for documentation of individual parameters you can specify.
@end defun
@cindex multiple X terminals
@cindex displays, multiple
- A single Emacs can talk to more than one X Windows display.
+ A single Emacs can talk to more than one X Window 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
corresponding to the currently selected frame): these are
@code{default-minibuffer-frame}, @code{defining-kbd-macro},
@code{last-kbd-macro}, and @code{system-key-alist}. These variables are
-always terminal-local and can never be buffer-local.
+always terminal-local and can never be buffer-local or frame-local
+(@pxref{Buffer-Local Variables}).
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
Frame parameters exist for the sake of window systems. A terminal frame
has a few parameters, mostly for compatibility's sake; only the height,
-width and @code{buffer-predicate} parameters really do something.
+width, @code{name}, @code{title}, @code{buffer-list} and
+@code{buffer-predicate} parameters do something special.
@menu
* Parameter Access:: How to change a frame's parameters.
* Initial Parameters:: Specifying frame parameters when you make a frame.
-* X Frame Parameters:: List of frame parameters.
+* Window Frame Parameters:: List of frame parameters for window systems.
* Size and Position:: Changing the size and position of a frame.
@end menu
@defvar initial-frame-alist
This variable's value is an alist of parameter values used when creating
-the initial X window frame. You can set this variable to specify the
+the initial window frame. You can set this variable to specify the
appearance of the initial frame without altering subsequent frames.
Each element has the form:
@defvar default-frame-alist
This is an alist specifying default values of frame parameters for all
-Emacs frames---the first frame, and subsequent frames. In many cases,
-you can get the same results by means of X resources.
+Emacs frames---the first frame, and subsequent frames. When using the X
+Window System, you can get the same results by means of X resources
+in many cases.
@end defvar
See also @code{special-display-frame-alist}, in @ref{Choosing Window}.
@code{initial-frame-alist} instead. @xref{Command Arguments,,, emacs,
The GNU Emacs Manual}.
-@node X Frame Parameters
-@subsection X Window Frame Parameters
+@node Window Frame Parameters
+@subsection 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; of these,
-@code{name}, @code{height}, @code{width}, and @code{buffer-predicate}
-provide meaningful information in non-X frames.
+uses. Here is a table of the parameters that have special meanings in a
+window frame; of these, @code{name}, @code{title}, @code{height},
+@code{width}, @code{buffer-list} and @code{buffer-predicate} provide
+meaningful information in terminal frames.
@table @code
+@item title
+If a frame has a non-@code{nil} title, it appears in the window system's
+border for the frame, and also in the mode line of windows in that frame
+if @code{mode-line-frame-identification} uses @samp{%F}
+(@pxref{%-Constructs}). This is normally the case when Emacs is not
+using a window system, and can only display one frame at a time.
+@xref{Frame Titles}.
+
@item name
-The name of the frame. Most window managers display the frame's name in
-the frame's border, at the top of the frame. If you don't specify a
-name, and you have more than one frame, Emacs sets the frame name based
-on the buffer displayed in the frame's selected window.
+The name of the frame. The frame name serves as a default for the frame
+title, if the @code{title} parameter is unspecified or @code{nil}. If
+you don't specify a name, Emacs sets the frame name automatically
+(@pxref{Frame Titles}).
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.
-Since a non-window terminal can display only one frame at a time, the
-frame name appears in the mode line.
-
@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
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. A positive value
-of @var{pos} counts toward the left. If the parameter is a negative
-integer @minus{}@var{pos} then @var{pos} is positive!
+of @var{pos} counts toward the left. @strong{Reminder:} if the
+parameter is a negative integer @minus{}@var{pos}, then @var{pos} is
+positive.
Some window managers ignore program-specified positions. If you want to
be sure the position you specify is not ignored, specify a
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. A positive value
-of @var{pos} counts toward the top. If the parameter is a negative
-integer @minus{}@var{pos} then @var{pos} is positive!
+of @var{pos} counts toward the top. @strong{Reminder:} if the
+parameter is a negative integer @minus{}@var{pos}, then @var{pos} is
+positive.
Some window managers ignore program-specified positions. If you want to
be sure the position you specify is not ignored, specify a
pixels, call @code{frame-pixel-width}; see @ref{Size and Position}.)
@item window-id
-The number of the X window for the frame.
+The number of the window-system window used by the frame.
@item minibuffer
Whether this frame has its own minibuffer. The value @code{t} means
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
+@code{nil}. It calls the predicate with one argument, a buffer, once for
each buffer; if the predicate returns a non-@code{nil} value, it
considers that buffer.
@item buffer-list
-A list of buffers recently selected in this frame.
+A list of buffers that have been selected in this frame,
+ordered most-recently-selected first.
@item font
The name of the font for displaying text in the frame. This is a
appears. If this is @code{nil}, the frame's title is used.
@item foreground-color
-The color to use for the image of a character. This is a string; the X
-server defines the meaningful color names.
+The color to use for the image of a character. This is a string; the
+window system defines the meaningful color names.
@item background-color
The color to use for the background of characters.
@defun x-parse-geometry geom
@cindex geometry specification
-The function @code{x-parse-geometry} converts a standard X windows
+The function @code{x-parse-geometry} converts a standard X Windows
geometry string to an alist that you can use as part of the argument to
@code{make-frame}.
@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.
+ Every frame has a @code{name} parameter; this serves as the default
+for the frame title which window systems typically display at the top of
+the frame. You can specify a name explicitly by setting the @code{name}
+frame property.
-Emacs computes the frame title based on a template stored in the
-variable @code{frame-title-format}.
+ Normally you don't specify the name explicitly, and Emacs computes the
+frame name automatically based on a template stored in the variable
+@code{frame-title-format}. Emacs recomputes the name each time the
+frame is redisplayed.
@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}.
+This variable specifies how to compute a name 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,
+This variable specifies how to compute the name for an iconified frame,
when you have not explicitly specified the frame title. This title
appears in the icon itself.
@end defvar
@var{frame}.
@end defun
-Conversely, selecting a window for Emacs with @code{select-window} also
+ Conversely, selecting a window for Emacs with @code{select-window} also
makes that window selected within its frame. @xref{Selecting Windows}.
-Another function that (usually) returns one of the windows in a frame is
-@code{minibuffer-window}. @xref{Minibuffer Misc}.
+ Another function that (usually) returns one of the windows in a given
+frame is @code{minibuffer-window}. @xref{Minibuffer Misc}.
@node Minibuffers and Frames
@section Minibuffers and Frames
This function returns the selected frame.
@end defun
-The X server normally directs keyboard input to the X window that the
-mouse is in. Some window managers use mouse clicks or keyboard events
-to @dfn{shift the focus} to various X windows, overriding the normal
-behavior of the server.
+Some window systems and window managers direct keyboard input to the
+window object that the mouse is in; others require explicit clicks or
+commands to @dfn{shift the focus} to various window objects. Either
+way, Emacs automatically keeps track of which frame has the focus.
-Lisp programs can switch frames ``temporarily'' by calling
-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.
+Lisp programs can also switch frames ``temporarily'' by calling the
+function @code{select-frame}. This does not alter the window system's
+concept of focus; 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} (@pxref{Mode Line Variables}).
+When using a text-only terminal, only the selected terminal frame is
+actually displayed on the terminal. @code{switch-frame} is the only way
+to switch frames, and the change lasts until overridden by a subsequent
+call to @code{switch-frame}. Each terminal screen except for the
+initial one has a number, and the number of the selected frame appears
+in the mode line after the word @samp{Emacs} (@pxref{Mode Line
+Variables}).
@c ??? This is not yet implemented properly.
@defun select-frame frame
until the next time this function is called.
@end defun
-Emacs cooperates with the X server and the window managers by arranging
-to select frames according to what the server and window manager ask
-for. It does so by generating a special kind of input event, called a
-@dfn{focus} event. The command loop handles a focus event by calling
+Emacs cooperates with the window system by arranging to select frames as
+the server and window manager request. It does so by generating a
+special kind of input event, called a @dfn{focus} event, when
+appropriate. The command loop handles a focus event by calling
@code{handle-switch-frame}. @xref{Focus Events}.
@deffn Command handle-switch-frame frame
change it.
@end defun
+@tindex focus-follows-mouse
+@defopt focus-follows-mouse
+This option is how you inform Emacs whether the window manager transfers
+focus when the user moves the mouse. Non-@code{nil} says that it does.
+When this is so, the command @code{other-frame} moves the mouse to a
+position consistent with the new selected frame.
+@end defopt
+
@node Visibility of Frames
@section Visibility of Frames
@cindex visible frame
@cindex iconified frame
@cindex frame visibility
-An X window frame may be @dfn{visible}, @dfn{invisible}, or
+A window 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
@end defun
The visibility status of a frame is also available as a frame
-parameter. You can read or change it as such. @xref{X Frame
+parameter. You can read or change it as such. @xref{Window Frame
Parameters}.
The user can iconify and deiconify frames with the window manager.
@node Raising and Lowering
@section Raising and Lowering Frames
- The X Window System uses a desktop metaphor. Part of this metaphor is
+ Most window systems use a desktop metaphor. Part of this metaphor is
the idea that windows are stacked in a notional third dimension
perpendicular to the screen surface, and thus ordered from ``highest''
-to ``lowest''. Where two X windows overlap, the one higher up covers
-the one underneath. Even an X window at the bottom of the stack can be
-seen if no other X window overlaps it.
+to ``lowest''. Where two windows overlap, the one higher up covers
+the one underneath. Even a window at the bottom of the stack can be
+seen if no other window overlaps it.
@cindex raising a frame
@cindex lowering a frame
- An X window's place in this ordering is not fixed; in fact, users tend
-to change the order frequently. @dfn{Raising} an X window means moving
-it ``up'', to the top of the stack. @dfn{Lowering} an X window means
+ A window's place in this ordering is not fixed; in fact, users tend
+to change the order frequently. @dfn{Raising} a window means moving
+it ``up'', to the top of the stack. @dfn{Lowering} a window means
moving it to the bottom of the stack. This motion is in the notional
-third dimension only, and does not change the position of the X window
+third dimension only, and does not change the position of the window
on the screen.
-You can raise and lower Emacs's X windows with these functions:
+ You can raise and lower Emacs frame Windows with these functions:
@deffn Command raise-frame frame
This function raises frame @var{frame}.
You can also enable auto-raise (raising automatically when a frame is
selected) or auto-lower (lowering automatically when it is deselected)
-for any frame using frame parameters. @xref{X Frame Parameters}.
+for any frame using frame parameters. @xref{Window Frame Parameters}.
@node Frame Configurations
@section Frame Configurations
A @dfn{frame configuration} records the current arrangement of frames,
all their properties, and the window configuration of each one.
+(@xref{Window Configurations}.)
@defun current-frame-configuration
This function returns a frame configuration list that describes
button.
@defspec track-mouse body@dots{}
-Execute @var{body}, meanwhile generating input events for mouse motion.
-The code in @var{body} can read these events with @code{read-event} or
-@code{read-key-sequence}. @xref{Motion Events}, for the format of mouse
-motion events.
+This special form executes @var{body}, with generation of mouse motion
+events enabled. Typically @var{body} would use @code{read-event} to
+read the motion events and modify the display accordingly. @xref{Motion
+Events}, for the format of mouse motion events.
The value of @code{track-mouse} is that of the last form in @var{body}.
+You should design @var{body} to return when it sees the up-event that
+indicates the release of the button, or whatever kind of event means
+it is time to stop tracking.
@end defspec
The usual purpose of tracking mouse motion is to indicate on the screen
These functions change the screen appearance instantaneously. The
effect is transient, only until the next ordinary Emacs redisplay. That
-is ok for mouse tracking, since it doesn't make sense for mouse tracking
+is OK for mouse tracking, since it doesn't make sense for mouse tracking
to change the text, and the body of @code{track-mouse} normally reads
the events itself and does not do redisplay.
@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.
+ When using a window system, a Lisp program can pop up a menu so that
+the user can choose an alternative with the mouse.
@defun x-popup-menu position menu
This function displays a pop-up menu and returns an indication of
@section Dialog Boxes
@cindex dialog boxes
- A dialog box is a variant of a pop-up menu. It looks a little
-different (if Emacs uses an X toolkit), it always appears in the center
-of a frame, and it has just one level and one pane. The main use of
-dialog boxes is for asking questions that the user can answer with
-``yes'', ``no'', and a few other alternatives. The functions
-@code{y-or-n-p} and @code{yes-or-no-p} use dialog boxes instead of the
-keyboard, when called from commands invoked by mouse clicks.
+ A dialog box is a variant of a pop-up menu---it looks a little
+different, it always appears in the center of a frame, and it has just
+one level and one pane. The main use of dialog boxes is for asking
+questions that the user can answer with ``yes'', ``no'', and a few other
+alternatives. The functions @code{y-or-n-p} and @code{yes-or-no-p} use
+dialog boxes instead of the keyboard, when called from commands invoked
+by mouse clicks.
@defun x-popup-dialog position contents
This function displays a pop-up dialog box and returns an indication of
@code{x-popup-menu}, but the precise coordinates don't matter; only the
frame matters.
-If your Emacs executable does not use an X toolkit, then it cannot
-display a real dialog box; so instead it displays the same items in a
-pop-up menu in the center of the frame.
+In some configurations, Emacs cannot display a real dialog box; so
+instead it displays the same items in a pop-up menu in the center of the
+frame.
@end defun
@node Pointer Shapes
@cindex mouse pointer shape
These variables specify which shape to use for the mouse pointer in
-various situations:
+various situations, when using the X Window System:
@table @code
@item x-pointer-shape
These variables affect newly created frames. They do not normally
affect existing frames; however, if you set the mouse color of a frame,
that also updates its pointer shapes based on the current values of
-these variables. @xref{X Frame Parameters}.
+these variables. @xref{Window Frame Parameters}.
The values you can use, to specify either of these pointer shapes, are
defined in the file @file{lisp/term/x-win.el}. Use @kbd{M-x apropos
@key{RET} x-pointer @key{RET}} to see a list of them.
-@node X Selections
-@section X Selections
+@node Window System Selections
+@section Window System Selections
@cindex selection (for X windows)
The X server records a set of @dfn{selections} which permit transfer of
@defun x-list-font pattern &optional face frame maximum
This function returns a list of available font names that match
-@var{pattern}. If the optional arguments FACE and FRAME are specified,
-then the list is limited to fonts that are the same size as @var{face}
-currently is on @var{frame}.
+@var{pattern}. If the optional arguments @var{face} and @var{frame} are
+specified, then the list is limited to fonts that are the same size as
+@var{face} currently is on @var{frame}.
The argument @var{pattern} should be a string, perhaps with wildcard
characters: the @samp{*} character matches any substring, and the
@tindex functionp
@defun functionp object
-This function returns @code{t} if @var{object} is any kind of function;
-that is, anything that could be called as a function.
+This function returns @code{t} if @var{object} is any kind of function,
+or a special form or macro.
@end defun
@defun subrp object
accessed.
It is a good idea to provide documentation strings for all the
-functions in your program, even those that are only called from within
+functions in your program, even those that are called only from within
your program. Documentation strings are like comments, except that they
are easier to access.
In most computer languages, every function has a name; the idea of a
function without a name is nonsensical. In Lisp, a function in the
strictest sense has no name. It is simply a list whose first element is
-@code{lambda}, or a primitive subr-object.
+@code{lambda}, a byte-code function object, or a primitive subr-object.
However, a symbol can serve as the name of a function. This happens
when you put the function in the symbol's @dfn{function cell}
which function to call, and how many arguments to give it, when you
write the program. Usually that's just what you want. Occasionally you
need to compute at run time which function to call. To do that, use the
-functions @code{funcall} and @code{apply}.
+function @code{funcall}. When you also need to determine at run time
+how may arguments to pass, use @code{apply}.
@defun funcall function &rest arguments
@code{funcall} calls @var{function} with @var{arguments}, and returns
list or other collection. Emacs Lisp has several such functions;
@code{mapcar} and @code{mapconcat}, which scan a list, are described
here. @xref{Creating Symbols}, for the function @code{mapatoms} which
-maps over the symbols in an obarray. @xref{Char-Tables}, for the
-function @code{map-char-table}, which maps over the elements in a
-char-table.
+maps over the symbols in an obarray.
+
+ These mapping functions do not allow char-tables because a char-table
+is a sparse array whose nominal range of indices is very large. To map
+over a char-table in a way that deals properly with its sparse nature,
+use the function @code{map-char-table} (@pxref{Char-Tables}).
@defun mapcar function sequence
@code{mapcar} applies @var{function} to each element of @var{sequence}
in turn, and returns a list of the results.
-The argument @var{sequence} may be a list, a vector, or a string. The
+The argument @var{sequence} can be any kind of sequence except a
+char-table; that is, a list, a vector, a bool-vector, or a string. The
result is always a list. The length of the result is the same as the
length of @var{sequence}.
@end group
@group
-(defun mapcar* (f &rest args)
+(defun mapcar* (function &rest args)
"Apply FUNCTION to successive cars of all ARGS.
Return the list of results."
;; @r{If no list is exhausted,}
(if (not (memq 'nil args))
- ;; @r{apply function to @sc{CAR}s.}
- (cons (apply f (mapcar 'car args))
- (apply 'mapcar* f
+ ;; @r{apply function to @sc{car}s.}
+ (cons (apply function (mapcar 'car args))
+ (apply 'mapcar* function
;; @r{Recurse for rest of elements.}
(mapcar 'cdr args)))))
@end group
other suitable punctuation.
The argument @var{function} must be a function that can take one
-argument and return a string.
+argument and return a string. The argument @var{sequence} can be any
+kind of sequence except a char-table; that is, a list, a vector, a
+bool-vector, or a string.
@smallexample
@group
@noindent
Here we define a function that uses @code{change-property},
-passing a function that doubles its argument:
+passing it a function to double a number:
@example
@group
@itemize @bullet
@item
-Copying one symbol's function definition to another. (In other words,
-making an alternate name for a function.)
+Copying one symbol's function definition to another---in other words,
+making an alternate name for a function. (If you think of this as the
+definition of the new name, you should use @code{defalias} instead of
+@code{fset}; see @ref{Defining Functions}.)
@item
Giving a symbol a function definition that is not a list and therefore
cannot be made with @code{defun}. For example, you can use @code{fset}
to give a symbol @code{s1} a function definition which is another symbol
@code{s2}; then @code{s1} serves as an alias for whatever definition
-@code{s2} presently has.
+@code{s2} presently has. (Once again use @code{defalias} instead of
+@code{fset} if you think of this as the definition of @code{s1}.)
@item
In constructs for defining or altering functions. If @code{defun}
@code{fset}.
@end itemize
-Here are examples of the first two uses:
+Here are examples of these uses:
@example
@group
-;; @r{Give @code{first} the same definition @code{car} has.}
-(fset 'first (symbol-function 'car))
- @result{} #<subr car>
-@end group
-@group
-(first '(1 2 3))
- @result{} 1
+;; @r{Save @code{foo}'s definition in @code{old-foo}.}
+(fset 'old-foo (symbol-function 'foo))
@end group
@group
;; @r{Make the symbol @code{car} the function definition of @code{xfirst}.}
+;; @r{(Most likely, @code{defalias} would be better than @code{fset} here.)}
(fset 'xfirst 'car)
@result{} car
@end group
(fset 'kill-two-lines "\^u2\^k")
@result{} "\^u2\^k"
@end group
-@end example
-See also the related function @code{defalias}, in @ref{Defining
-Functions}.
+@group
+;; @r{Here is a function that alters other functions.}
+(defun copy-function-definition (new old)
+ "Define NEW with the same function definition as OLD."
+ (fset new (symbol-function old)))
+@end group
+@end example
@end defun
When writing a function that extends a previously defined function,
file is loaded before moving aside the old definition of @code{foo}.
But it is unmodular and unclean, in any case, for a Lisp file to
-redefine a function defined elsewhere.
+redefine a function defined elsewhere. It is cleaner to use the advice
+facility (@pxref{Advising Functions}).
@node Inline Functions
@section Inline Functions
generally should not make large functions inline.
It's possible to define a macro to expand into the same code that an
-inline function would execute. But the macro would have a limitation:
-you can use it only explicitly---a macro cannot be called with
+inline function would execute. (@xref{Macros}.) But the macro would be
+limited to direct use in expressions---a macro cannot be called with
@code{apply}, @code{mapcar} and so on. Also, it takes some work to
-convert an ordinary function into a macro. (@xref{Macros}.) To convert
-it into an inline function is very easy; simply replace @code{defun}
-with @code{defsubst}. Since each argument of an inline function is
-evaluated exactly once, you needn't worry about how many times the
-body uses the arguments, as you do for macros. (@xref{Argument
-Evaluation}.)
+convert an ordinary function into a macro. To convert it into an inline
+function is very easy; simply replace @code{defun} with @code{defsubst}.
+Since each argument of an inline function is evaluated exactly once, you
+needn't worry about how many times the body uses the arguments, as you
+do for macros. (@xref{Argument Evaluation}.)
Inline functions can be used and open-coded later on in the same file,
following the definition, just like macros.
@item funcall
See @ref{Calling Functions}.
+@item function
+See @ref{Anonymous Functions}.
+
@item ignore
See @ref{Calling Functions}.
@item mapcar
See @ref{Mapping Functions}.
+@item map-char-table
+See @ref{Char-Tables}.
+
@item mapconcat
See @ref{Mapping Functions}.
sentence (or two complete sentences) since some commands, such as
@code{apropos}, show only the first line of a multi-line documentation
string. Also, you should not indent the second line of a documentation
-string, if you have one, because that looks odd when you use @kbd{C-h f}
-(@code{describe-function}) or @kbd{C-h v} (@code{describe-variable}).
-@xref{Documentation Tips}.
+string, if it has one, because that looks odd when you use @kbd{C-h f}
+(@code{describe-function}) or @kbd{C-h v} (@code{describe-variable}) to
+view the documentation string. @xref{Documentation Tips}.
- Documentation strings may contain several special substrings, which
+ Documentation strings can contain several special substrings, which
stand for key bindings to be looked up in the current keymaps when the
documentation is displayed. This allows documentation strings to refer
to the keys for related commands and be accurate even when a user
value containing the actual (current) key bindings.
The function @code{documentation} signals a @code{void-function} error
-if @var{function} has no function definition. However, it is ok if
+if @var{function} has no function definition. However, it is OK if
the function definition has no documentation string. In that case,
@code{documentation} returns @code{nil}.
@end defun
@c Emacs 19 feature
@defvar doc-directory
-This variable holds the name of the directory which should contion the
+This variable holds the name of the directory which should contain the
file @code{"DOC-@var{version}"} that contains documentation strings for
built-in and preloaded functions and variables.
@var{command}} if @var{command} has no key bindings.
@item \@{@var{mapvar}@}
-stands for a summary of the value of @var{mapvar}. The value should be
-a keymap. The summary is made by @code{describe-bindings}.
+stands for a summary of the keymap which is the value of the variable
+@var{mapvar}. The summary is made using @code{describe-bindings}.
@item \<@var{mapvar}>
stands for no text itself. It is used only for a side effect: it
-specifies @var{mapvar} as the keymap for any following
+specifies @var{mapvar}'s value as the keymap for any following
@samp{\[@var{command}]} sequences in this documentation string.
@item \=
? minibuffer-completion-help
SPC minibuffer-complete-word
TAB minibuffer-complete
-LFD minibuffer-complete-and-exit
+C-j minibuffer-complete-and-exit
RET minibuffer-complete-and-exit
C-g abort-recursive-edit
"
Emacs notation for keyboard input. A normal printing character appears
as itself, but a control character turns into a string starting with
@samp{C-}, a meta character turns into a string starting with @samp{M-},
-and space, linefeed, etc.@: appear as @samp{SPC}, @samp{LFD}, etc. A
+and space, tab, etc.@: appear as @samp{SPC}, @samp{TAB}, etc. A
function key symbol appears as itself. An event that is a list appears
as the name of the symbol in the @sc{car} of the list.
@end group
@group
(key-description "\C-x \M-y \n \t \r \f123")
- @result{} "C-x SPC M-y SPC LFD SPC TAB SPC RET SPC C-l 1 2 3"
+ @result{} "C-x SPC M-y SPC C-j SPC TAB SPC RET SPC C-l 1 2 3"
@end group
@group
(single-key-description 'C-mouse-1)
about them, see @ref{Help, , Help, emacs, The GNU Emacs Manual}. Here
we describe some program-level interfaces to the same information.
-@deffn Command apropos regexp &optional do-all predicate
+@deffn Command apropos regexp &optional do-all
This function finds all symbols whose names contain a match for the
regular expression @var{regexp}, and returns a list of them
(@pxref{Regular Expressions}). It also displays the symbols in a buffer
If @var{do-all} is non-@code{nil}, then @code{apropos} also shows
key bindings for the functions that are found.
-If @var{predicate} is non-@code{nil}, it should be a function to be
-called on each symbol that has matched @var{regexp}. Only symbols for
-which @var{predicate} returns a non-@code{nil} value are listed or
-displayed.
-
In the first of the following examples, @code{apropos} finds all the
-symbols with names containing @samp{exec}. In the second example, it
-finds and returns only those symbols that are also commands. (We don't
-show here the output that results in the @samp{*Help*} buffer.)
+symbols with names containing @samp{exec}. (We don't show here the
+output that results in the @samp{*Help*} buffer.)
@smallexample
@group
exec-path execute-extended-command execute-kbd-macro
executing-kbd-macro executing-macro)
@end group
-
-@group
-(apropos "exec" nil 'commandp)
- @result{} (Buffer-menu-execute execute-extended-command)
-@end group
-@ignore
-@group
----------- Buffer: *Help* ----------
-Buffer-menu-execute
- Function: Save and/or delete buffers marked with
- M-x Buffer-menu-save or M-x Buffer-menu-delete commands.
-execute-extended-command ESC x
- Function: Read function name, then read its
- arguments and call it.
----------- Buffer: *Help* ----------
-@end group
-@end ignore
@end smallexample
-
-The command @kbd{C-h a} (@code{command-apropos}) calls @code{apropos},
-but specifies a @var{predicate} that restricts the output to symbols
-that are commands. The call to @code{apropos} looks like this:
-
-@smallexample
-(apropos string t 'commandp)
-@end smallexample
-@end deffn
-
-@c Emacs 19 feature
-@deffn Command super-apropos regexp &optional do-all
-This function differs from @code{apropos} in that it searches
-documentation strings as well as symbol names for matches for
-@var{regexp}. By default, it searches the documentation strings for
-preloaded functions and variables only. If @var{do-all} is
-non-@code{nil}, it scans the names and documentation strings of all
-functions and variables.
@end deffn
@defvar help-map
@defvar help-char
The value of this variable is the help character---the character that
-Emacs recognizes as meaning Help. By default, it is 8, which is
+Emacs recognizes as meaning Help. By default, it stands for 8, which is
@kbd{C-h}. When Emacs reads this character, if @code{help-form} is
non-@code{nil} Lisp expression, it evaluates that expression, and
displays the result in a window if it is a string.
subcommands of the prefix key.
@end defvar
+@tindex help-event-list
+@defvar help-event-list
+The value of this variable is a list of event types that serve as
+alternative ``help characters.'' These events are handled just like the
+event specified by @code{help-char}.
+@end defvar
+
@defvar help-form
If this variable is non-@code{nil}, its value is a form to evaluate
whenever the character @code{help-char} is read. If evaluating the form
A command that calls @code{read-event} or @code{read-char} probably
should bind @code{help-form} to a non-@code{nil} expression while it
-does input. (The exception is when @kbd{C-h} is meaningful input.)
-Evaluating this expression should result in a string that explains what
-the input is for and how to enter it properly.
+does input. (The time when you should not do this is when @kbd{C-h} has
+some other meaning.) Evaluating this expression should result in a
+string that explains what the input is for and how to enter it properly.
Entry to the minibuffer binds this variable to the value of
@code{minibuffer-help-form} (@pxref{Minibuffer Misc}).
@end defvar
@defvar prefix-help-command
-This variable holds a function to print help for a prefix character.
-The function is called when the user types a prefix key followed by the
-help character, and the help character has no binding after that prefix.
-The variable's default value is @code{describe-prefix-bindings}.
+This variable holds a function to print help for a prefix key. The
+function is called when the user types a prefix key followed by the help
+character, and the help character has no binding after that prefix. The
+variable's default value is @code{describe-prefix-bindings}.
@end defvar
@defun describe-prefix-bindings
internal aspects of GNU Emacs that may be of interest to C programmers.
@menu
-* Building Emacs:: How to preload Lisp libraries into Emacs.
+* Building Emacs:: How to the dumped Emacs is made.
* Pure Storage:: A kludge to make preloaded Lisp functions sharable.
* Garbage Collection:: Reclaiming space for Lisp objects no longer used.
+* Memory Usage:: Info about total size of Lisp objects made so far.
* Writing Emacs Primitives:: Writing C code for Emacs.
* Object Internals:: Data formats of buffers, windows, processes.
@end menu
-@node Building Emacs, Pure Storage, GNU Emacs Internals, GNU Emacs Internals
+@node Building Emacs
@appendixsec Building Emacs
@cindex building Emacs
@pindex temacs
you must run Emacs with @samp{-batch}.
@end defun
-@deffn Command emacs-version
- This function returns a string describing the version of Emacs that is
-running. It is useful to include this string in bug reports.
-
-@example
-@group
-(emacs-version)
- @result{} "GNU Emacs 20.2.5 (i486-pc-linux-gnulibc1, X toolkit)
- of Sat Feb 14 1998 on psilocin.gnu.org"
-@end group
-@end example
-
-Called interactively, the function prints the same information in the
-echo area.
-@end deffn
-
-@defvar emacs-build-time
-The value of this variable is the time at which Emacs was built at the
-local site.
-
-@example
-@group
-emacs-build-time
- @result{} "Tue Jun 6 14:55:57 1995"
-@end group
-@end example
-@end defvar
-
-@defvar emacs-version
-The value of this variable is the version of Emacs being run. It is a
-string such as @code{"20.3.1"}. The last number in this string is not
-really part of the Emacs release version number; it is incremented each
-time you build Emacs in any given directory.
-@end defvar
-
- The following two variables have existed since Emacs version 19.23,
-
-@defvar emacs-major-version
-The major version number of Emacs, as an integer. For Emacs version
-20.2, the value is 20.
-@end defvar
-
-@defvar emacs-minor-version
-The minor version number of Emacs, as an integer. For Emacs version
-20.2, the value is 2.
-@end defvar
-
-@node Pure Storage, Garbage Collection, Building Emacs, GNU Emacs Internals
+@node Pure Storage
@appendixsec Pure Storage
@cindex pure storage
You should not change this flag in a running Emacs.
@end defvar
-@node Garbage Collection, Writing Emacs Primitives, Pure Storage, GNU Emacs Internals
+@node Garbage Collection
@appendixsec Garbage Collection
@cindex garbage collector
((@var{used-conses} . @var{free-conses})
(@var{used-syms} . @var{free-syms})
@end group
- (@var{used-markers} . @var{free-markers})
+ (@var{used-miscs} . @var{free-miscs})
@var{used-string-chars}
@var{used-vector-slots}
(@var{used-floats} . @var{free-floats})
(@var{used-intervals} . @var{free-intervals}))
+@end example
+
+Here is an example:
+
+@example
@group
(garbage-collect)
@result{} ((106886 . 13184) (9769 . 0)
The number of symbols for which space has been obtained from the
operating system, but that are not currently being used.
-@item used-markers
-The number of markers in use.
+@item used-miscs
+The number of miscellaneous objects in use. These include markers and
+overlays, plus certain objects not visible to users.
-@item free-markers
-The number of markers for which space has been obtained from the
-operating system, but that are not currently being used.
+@item free-miscs
+The number of miscellaneous objects for which space has been obtained
+from the operating system, but that are not currently being used.
@item used-string-chars
The total size of all strings, in characters.
@code{garbage-collect} will set the threshold back to 10,000.
@end defopt
+ The value return by @code{garbage-collect} describes the amount of
+memory used by Lisp data, broken down by data type. By contrast, the
+function @code{memory-limit} provides information on the total amount of
+memory Emacs is currently using.
+
@c Emacs 19 feature
@defun memory-limit
This function returns the address of the last byte Emacs has allocated,
memory usage.
@end defun
-@node Writing Emacs Primitives, Object Internals, Garbage Collection, GNU Emacs Internals
+@node Memory Usage
+@section Memory Usage
+
+ These functions and variables give information about the total amount
+of memory allocation that Emacs has done, broken down by data type.
+Note the difference between these and the values returned by
+@code{(garbage-collect)}; those count objects that currently exist, but
+these count the number or size of all allocations, including those for
+objects that have since been freed.
+
+@defvar cons-cells-consed
+The total number of cons cells that have been allocated so far
+in this Emacs session.
+@end defvar
+
+@defvar floats-consed
+The total number of floats that have been allocated so far
+in this Emacs session.
+@end defvar
+
+@defvar vector-cells-consed
+The total number of vector cells that have been allocated so far
+in this Emacs session.
+@end defvar
+
+@defvar symbols-consed
+The total number of symbols that have been allocated so far
+in this Emacs session.
+@end defvar
+
+@defvar string-chars-consed
+The total number of string characters that have been allocated so far
+in this Emacs session.
+@end defvar
+
+@defvar misc-objects-consed
+The total number of miscellaneous objects that have been allocated so
+far in this Emacs session. These include markers and overlays, plus
+certain objects not visible to users.
+@end defvar
+
+@defvar intervals-consed
+The total number of intervals that have been allocated so far
+in this Emacs session.
+@end defvar
+
+@node Writing Emacs Primitives
@appendixsec Writing Emacs Primitives
@cindex primitive function internals
@code{DEFVAR_BOOL} makes a C variable of type @code{int} visible in Lisp
with a value that is either @code{t} or @code{nil}.
+ If you define a file-scope C variable of type @code{Lisp_Object},
+you must protect it for garbage-collection by calling @code{staticpro}
+in @code{syms_of_@var{filename}}, like this:
+
+@example
+staticpro (&@var{variable});
+@end example
+
Here is another example function, with more complicated arguments.
-This comes from the code for the X Window System, and it demonstrates
-the use of macros and functions to manipulate Lisp objects.
+This comes from the code in @file{window.c}, and it demonstrates the use
+of macros and functions to manipulate Lisp objects.
@smallexample
@group
DEFUN ("coordinates-in-window-p", Fcoordinates_in_window_p,
Scoordinates_in_window_p, 2, 2,
"xSpecify coordinate pair: \nXExpression which evals to window: ",
- "Return non-nil if POSITIONS is in WINDOW.\n\
- \(POSITIONS is a list, (SCREEN-X SCREEN-Y)\)\n\
+ "Return non-nil if COORDINATES is in WINDOW.\n\
+COORDINATES is a cons of the form (X . Y), X and Y being distances\n\
+...
@end group
@group
- Returned value is list of positions expressed\n\
- relative to window upper left corner.")
- (coordinate, window)
- register Lisp_Object coordinate, window;
+If they are on the border between WINDOW and its right sibling,\n\
+ `vertical-line' is returned.")
+ (coordinates, window)
+ register Lisp_Object coordinates, window;
@{
- register Lisp_Object xcoord, ycoord;
+ int x, y;
@end group
@group
- if (!CONSP (coordinate)) wrong_type_argument (Qlistp, coordinate);
- CHECK_WINDOW (window, 2);
- xcoord = Fcar (coordinate);
- ycoord = Fcar (Fcdr (coordinate));
- CHECK_NUMBER (xcoord, 0);
- CHECK_NUMBER (ycoord, 1);
+ CHECK_LIVE_WINDOW (window, 0);
+ CHECK_CONS (coordinates, 1);
+ x = XINT (Fcar (coordinates));
+ y = XINT (Fcdr (coordinates));
@end group
+
@group
- if ((XINT (xcoord) < XINT (XWINDOW (window)->left))
- || (XINT (xcoord) >= (XINT (XWINDOW (window)->left)
- + XINT (XWINDOW (window)->width))))
- return Qnil;
- /* @r{Subtracting from XFASTINT (xcoord) is safe}
- @r{as long as we know the result is not negative.} */
- XFASTINT (xcoord) -= XFASTINT (XWINDOW (window)->left);
+ switch (coordinates_in_window (XWINDOW (window), &x, &y))
+ @{
+ case 0: /* NOT in window at all. */
+ return Qnil;
@end group
+
@group
- if (XINT (ycoord) == (screen_height - 1))
- return Qnil;
+ case 1: /* In text part of window. */
+ return Fcons (make_number (x), make_number (y));
@end group
+
@group
- if ((XINT (ycoord) < XINT (XWINDOW (window)->top))
- || (XINT (ycoord) >= (XINT (XWINDOW (window)->top)
- + XINT (XWINDOW (window)->height)) - 1))
- return Qnil;
+ case 2: /* In mode line of window. */
+ return Qmode_line;
@end group
+
@group
- XFASTINT (ycoord) -= XFASTINT (XWINDOW (window)->top);
- return (Fcons (xcoord, Fcons (ycoord, Qnil)));
+ case 3: /* On right border of window. */
+ return Qvertical_line;
+@end group
+
+@group
+ default:
+ abort ();
+ @}
@}
@end group
@end smallexample
@file{lisp.h} contains the definitions for some important macros and
functions.
-@node Object Internals, , Writing Emacs Primitives, GNU Emacs Internals
+@node Object Internals
@appendixsec Object Internals
@cindex object internals
* Process Internals:: Components of a process structure.
@end menu
-@node Buffer Internals, Window Internals, Object Internals, Object Internals
+@node Buffer Internals
@appendixsubsec Buffer Internals
@cindex internals, of buffer
@cindex buffer internals
@item downcase_table
This field contains the conversion table for converting text to lower case.
-@xref{Case Table}.
+@xref{Case Tables}.
@item upcase_table
This field contains the conversion table for converting text to upper case.
-@xref{Case Table}.
+@xref{Case Tables}.
@item case_canon_table
This field contains the conversion table for canonicalizing text for
-case-folding search. @xref{Case Table}.
+case-folding search. @xref{Case Tables}.
@item case_eqv_table
This field contains the equivalence table for case-folding search.
-@xref{Case Table}.
+@xref{Case Tables}.
@item display_table
This field contains the buffer's display table, or @code{nil} if it doesn't
This field is non-@code{nil} if the buffer's mark is active.
@item local_var_alist
-This field contains the association list describing the variables local
-in this buffer, and their values, with the exception of local variables
-that have special slots in the buffer object. (Those slots are omitted
-from this table.) @xref{Buffer-Local Variables}.
+This field contains the association list describing the buffer-local
+variable bindings of this buffer, not including the built-in
+buffer-local bindings that that have special slots in the buffer object.
+(Those slots are omitted from this table.) @xref{Buffer-Local
+Variables}.
@item base_buffer
This field holds the buffer's base buffer (if it is an indirect buffer),
This field holds a list of the overlays in this buffer that end after
the current overlay center position. They are sorted in order of
increasing beginning position.
+
+@item enable_multibyte_characters
+This field holds the buffer's local value of
+@code{enable-multibyte-characters}---either @code{t} or @code{nil}.
@end table
-@node Window Internals, Process Internals, Buffer Internals, Object Internals
+@node Window Internals
@appendixsubsec Window Internals
@cindex internals, of window
@cindex window internals
this field is @code{nil}.
@end table
-@node Process Internals, , Window Internals, Object Internals
+@node Process Internals
@appendixsubsec Process Internals
@cindex internals, of process
@cindex process internals
with its own idiosyncrasies. Many of them were inspired by Maclisp,
which was written in the 1960's at MIT's Project MAC. Eventually the
implementors of the descendants of Maclisp came together and developed a
-standard for Lisp systems, called Common Lisp.
+standard for Lisp systems, called Common Lisp. In the mean time, Gerry
+Sussman and Guy Steele at MIT developed a simplified but very powerful
+dialect of Lisp, called Scheme.
GNU Emacs Lisp is largely inspired by Maclisp, and a little by Common
Lisp. If you know Common Lisp, you will notice many similarities.
Lisp differs from Common Lisp. If you don't know Common Lisp, don't
worry about it; this manual is self-contained.
+ Emacs Lisp is not at all influenced by Scheme; but the GNU project has
+an implementation of Scheme, called Guile. We use Guile for
+extensibility in all new GNU software that calls for extensibility.
+
@node Conventions
@section Conventions
* Error Messages:: The format we use for examples of errors.
* Buffer Text Notation:: The format we use for buffer contents in examples.
* Format of Descriptions:: Notation for describing functions, variables, etc.
+* Version Info:: Which Emacs version is running?
@end menu
@node Some Terms
@cindex fonts
Examples of Lisp code appear in this font or form: @code{(list 1 2
-3)}. Names that represent arguments or metasyntactic variables appear
-in this font or form: @var{first-number}.
+3)}. Names that represent metasyntactic variables, or arguments to a
+function being described, appear in this font or form:
+@var{first-number}.
@node nil and t
@subsection @code{nil} and @code{t}
In Emacs Lisp, @code{nil} and @code{t} are special symbols that always
evaluate to themselves. This is so that you do not need to quote them
to use them as constants in a program. An attempt to change their
-values results in a @code{setting-constant} error. @xref{Accessing
+values results in a @code{setting-constant} error. The same is true of
+any symbol whose name starts with a colon (@samp{:}). @xref{Constant
Variables}.
@node Evaluation Notation
name. In addition, @samp{@point{}} indicates the location of point.
(The symbol for point, of course, is not part of the text in the buffer;
it indicates the place @emph{between} two characters where point is
-located.)
+currently located.)
@example
---------- Buffer: foo ----------
@cindex special form descriptions
In a function description, the name of the function being described
-appears first. It is followed on the same line by a list of parameters.
-The names used for the parameters are also used in the body of the
-description.
+appears first. It is followed on the same line by a list of argument
+names. These names are also used in the body of the description, to
+stand for the values of the arguments.
- The appearance of the keyword @code{&optional} in the parameter list
-indicates that the arguments for subsequent parameters may be omitted
-(omitted parameters default to @code{nil}). Do not write
-@code{&optional} when you call the function.
+ The appearance of the keyword @code{&optional} in the argument list
+indicates that the subsequent arguments may be omitted (omitted
+arguments default to @code{nil}). Do not write @code{&optional} when
+you call the function.
The keyword @code{&rest} (which will always be followed by a single
-parameter) indicates that any number of arguments can follow. The value
-of the single following parameter will be a list of all these arguments.
+argument name) indicates that any number of arguments can follow. The value
+of the single following arguments name will be a list of all these arguments.
Do not write @code{&rest} when you call the function.
Here is a description of an imaginary function @code{foo}:
@end example
@end defun
- Any parameter whose name contains the name of a type (e.g.,
+ Any argument whose name contains the name of a type (e.g.,
@var{integer}, @var{integer1} or @var{buffer}) is expected to be of that
type. A plural of a type (such as @var{buffers}) often means a list of
-objects of that type. Parameters named @var{object} may be of any type.
-(@xref{Lisp Data Types}, for a list of Emacs object types.)
-Parameters with other sorts of names (e.g., @var{new-file}) are
-discussed specifically in the description of the function. In some
-sections, features common to parameters of several functions are
-described at the beginning.
+objects of that type. Arguments named @var{object} may be of any type.
+(@xref{Lisp Data Types}, for a list of Emacs object types.) Arguments
+with other sorts of names (e.g., @var{new-file}) are discussed
+specifically in the description of the function. In some sections,
+features common to the arguments of several functions are described at
+the beginning.
@xref{Lambda Expressions}, for a more complete description of optional
and rest arguments.
(the arguments are not evaluated), but are presented the same way.
Special form descriptions use a more complex notation to specify
-optional and repeated parameters because they can break the argument
+optional and repeated arguments because they can break the argument
list down into separate arguments in more complicated ways.
@samp{@code{@r{[}@var{optional-arg}@r{]}}} means that @var{optional-arg} is
optional and @samp{@var{repeated-args}@dots{}} stands for zero or more
@example
(count-loop (i 0 10)
(prin1 i) (princ " ")
- (prin1 (aref vector i)) (terpri))
+ (prin1 (aref vector i))
+ (terpri))
@end example
If @var{from} and @var{to} are omitted, then @var{var} is bound to
User option descriptions have the same format, but `Variable' is
replaced by `User Option'.
+@node Version Info
+@section Version Information
+
+ These functions and variables provide information about which
+version of Emacs is in use.
+
+@deffn Command emacs-version
+This function returns a string describing the version of Emacs that is
+running. It is useful to include this string in bug reports.
+
+@example
+@group
+(emacs-version)
+ @result{} "GNU Emacs 20.3.5 (i486-pc-linux-gnulibc1, X toolkit)
+ of Sat Feb 14 1998 on psilocin.gnu.org"
+@end group
+@end example
+
+Called interactively, the function prints the same information in the
+echo area.
+@end deffn
+
+@defvar emacs-build-time
+The value of this variable is the time at which Emacs was built at the
+local site.
+
+@example
+@group
+emacs-build-time
+ @result{} "Tue Jun 6 14:55:57 1995"
+@end group
+@end example
+@end defvar
+
+@defvar emacs-version
+The value of this variable is the version of Emacs being run. It is a
+string such as @code{"20.3.1"}. The last number in this string is not
+really part of the Emacs release version number; it is incremented each
+time you build Emacs in any given directory.
+@end defvar
+
+ The following two variables have existed since Emacs version 19.23,
+
+@defvar emacs-major-version
+The major version number of Emacs, as an integer. For Emacs version
+20.3, the value is 20.
+@end defvar
+
+@defvar emacs-minor-version
+The minor version number of Emacs, as an integer. For Emacs version
+20.3, the value is 3.
+@end defvar
+
@node Acknowledgements
@section Acknowledgements
A @dfn{keymap} is a table mapping event types to definitions (which
can be any Lisp objects, though only certain types are meaningful for
execution by the command loop). Given an event (or an event type) and a
-keymap, Emacs can get the event's definition. Events include ordinary
-@sc{ASCII} characters, function keys, and mouse actions (@pxref{Input
-Events}).
+keymap, Emacs can get the event's definition. Events include
+characters, function keys, and mouse actions (@pxref{Input Events}).
A sequence of input events that form a unit is called a
@dfn{key sequence}, or @dfn{key} for short. A sequence of one event
@item @var{vector}
If an element of a keymap is a vector, the vector counts as bindings for
-all the @sc{ASCII} characters; vector element @var{n} is the binding for
-the character with code @var{n}. This is a compact way to record lots
-of bindings. A keymap with such a vector is called a @dfn{full keymap}.
-Other keymaps are called @dfn{sparse keymaps}.
+all the @sc{ASCII} characters, codes 0 through 127; vector element
+@var{n} is the binding for the character with code @var{n}. This is a
+compact way to record lots of bindings. A keymap with such a vector is
+called a @dfn{full keymap}. Other keymaps are called @dfn{sparse
+keymaps}.
When a keymap contains a vector, it always defines a binding for each
@sc{ASCII} character, even if the vector contains @code{nil} for that
-character. Such a binding of @code{nil} overrides any default binding
-in the keymap. However, default bindings are still meaningful for
-events that are not @sc{ASCII} characters. A binding of @code{nil} does
-@emph{not} override lower-precedence keymaps; thus, if the local map
-gives a binding of @code{nil}, Emacs uses the binding from the global
-map.
+character. Such a binding of @code{nil} overrides any default key
+binding in the keymap. However, default bindings are still meaningful
+for events that are not @sc{ASCII} characters. A binding of @code{nil}
+does @emph{not} override lower-precedence keymaps; thus, if the local
+map gives a binding of @code{nil}, Emacs uses the binding from the
+global map.
@item @var{string}
@cindex keymap prompt string
@cindex prefix key
A @dfn{prefix key} is a key sequence whose binding is a keymap. The
-keyamp defines what to do with key sequences that extend the prefix key.
+keymap defines what to do with key sequences that extend the prefix key.
For example, @kbd{C-x} is a prefix key, and it uses a keymap that is
also stored in the variable @code{ctl-x-map}. This keymap defines
bindings for key sequences starting with @kbd{C-x}.
All the active keymaps are used together to determine what command to
execute when a key is entered. Emacs searches these maps one by one, in
-order of decreasing precedence, until it finds a binding in one of the maps.
+order of decreasing precedence, until it finds a binding in one of the
+maps. The procedure for searching a single keymap is called @dfn{key
+lookup}; see @ref{Key Lookup}.
- Normally, Emacs @emph{first} searches for the key in the minor mode
+Normally, Emacs first searches for the key in the minor mode
maps (one map at a time); if they do not supply a binding for the key,
Emacs searches the local map; if that too has no binding, Emacs then
searches the global map. However, if @code{overriding-local-map} is
non-@code{nil}, Emacs searches that map first, before the global map.
- The procedure for searching a single keymap is called
-@dfn{key lookup}; see @ref{Key Lookup}.
-
@cindex major mode keymap
Since every buffer that uses the same major mode normally uses the
same local keymap, you can think of the keymap as local to the mode. A
change to the local keymap of a buffer (using @code{local-set-key}, for
example) is seen also in the other buffers that share that keymap.
- The local keymaps that are used for Lisp mode, C mode, and several
-other major modes exist even if they have not yet been used. These
-local maps are the values of the variables @code{lisp-mode-map},
-@code{c-mode-map}, and so on. For most other modes, which are less
-frequently used, the local keymap is constructed only when the mode is
-used for the first time in a session.
+ The local keymaps that are used for Lisp mode and some other major
+modes exist even if they have not yet been used. These local maps are
+the values of variables such as @code{lisp-mode-map}. For most major
+modes, which are less frequently used, the local keymap is constructed
+only when the mode is used for the first time in a session.
The minibuffer has local keymaps, too; they contain various completion
and exit commands. @xref{Intro to Minibuffers}.
Note that elements of @code{minor-mode-map-alist} do not have the same
structure as elements of @code{minor-mode-alist}. The map must be the
@sc{cdr} of the element; a list with the map as the @sc{cadr} will not
-do.
-
-What's more, the keymap itself must appear in the @sc{cdr}. It does not
-work to store a variable in the @sc{cdr} and make the map the value of
-that variable.
+do. The @sc{cadr} can be either a keymap (a list) or a symbol
+whose function definition is a keymap.
When more than one minor mode keymap is active, their order of priority
is the order of @code{minor-mode-map-alist}. But you should design
This variable allows major modes to override the key bindings for
particular minor modes. The elements of this alist look like the
elements of @code{minor-mode-map-alist}: @code{(@var{variable}
-. @var{keymap})}. If a variable has an element
-@code{minor-mode-overriding-map-alist}. that map overrides the one in
-@code{minor-mode-map-alist}.
+. @var{keymap})}. If a variable appears an element
+@code{minor-mode-overriding-map-alist}, that element overrides any
+element for the same variable in @code{minor-mode-map-alist}.
-@code{minor-mode-overriding-map-alist} is automatically local in all
-buffers.
+@code{minor-mode-overriding-map-alist} is automatically buffer-local in
+all buffers.
@end defvar
@defvar overriding-local-map
Let's use the term @dfn{keymap entry} to describe the value found by
looking up an event type in a keymap. (This doesn't include the item
-string and other extra elements in menu key bindings because
+string and other extra elements in menu key bindings, because
@code{lookup-key} and other key lookup functions don't include them in
the returned value.) While any Lisp object may be stored in a keymap as
-a keymap entry, not all make sense for key lookup. Here is a list of
+a keymap entry, not all make sense for key lookup. Here is a table of
the meaningful kinds of keymap entries:
@table @asis
has no default binding, that is equivalent to a binding of @code{nil}
for that event type.
-@item @var{keymap}
-@cindex keymap in keymap
-The events used so far in the lookup form a prefix key. The next
-event of the key sequence is looked up in @var{keymap}.
-
@item @var{command}
@cindex command in keymap
The events used so far in the lookup form a complete key,
used so far in the lookup form a complete key, and the array is its
binding. See @ref{Keyboard Macros}, for more information.
+@item @var{keymap}
+@cindex keymap in keymap
+The events used so far in the lookup form a prefix key. The next
+event of the key sequence is looked up in @var{keymap}.
+
@item @var{list}
@cindex list in keymap
The meaning of a list depends on the types of the elements of the list.
Here are the functions and variables pertaining to key lookup.
@defun lookup-key keymap key &optional accept-defaults
-This function returns the definition of @var{key} in @var{keymap}. If
-the string or vector @var{key} is not a valid key sequence according to
-the prefix keys specified in @var{keymap}, it must be ``too long'' and
-have extra events at the end that do not fit into a single key sequence.
-Then the value is a number, the number of events at the front of
-@var{key} that compose a complete key.
-
-@c Emacs 19 feature
-If @var{accept-defaults} is non-@code{nil}, then @code{lookup-key}
-considers default bindings as well as bindings for the specific events
-in @var{key}. Otherwise, @code{lookup-key} reports only bindings for
-the specific sequence @var{key}, ignoring default bindings except when
-you explicitly ask about them. (To do this, supply @code{t} as an
-element of @var{key}; see @ref{Format of Keymaps}.)
-
-All the other functions described in this chapter that look up keys use
-@code{lookup-key}.
+This function returns the definition of @var{key} in @var{keymap}. All
+the other functions described in this chapter that look up keys use
+@code{lookup-key}. Here are examples:
@example
@group
@end group
@end example
- If @var{key} contains a meta character, that character is implicitly
+If the string or vector @var{key} is not a valid key sequence according
+to the prefix keys specified in @var{keymap}, it must be ``too long''
+and have extra events at the end that do not fit into a single key
+sequence. Then the value is a number, the number of events at the front
+of @var{key} that compose a complete key.
+
+@c Emacs 19 feature
+If @var{accept-defaults} is non-@code{nil}, then @code{lookup-key}
+considers default bindings as well as bindings for the specific events
+in @var{key}. Otherwise, @code{lookup-key} reports only bindings for
+the specific sequence @var{key}, ignoring default bindings except when
+you explicitly ask about them. (To do this, supply @code{t} as an
+element of @var{key}; see @ref{Format of Keymaps}.)
+
+If @var{key} contains a meta character, that character is implicitly
replaced by a two-character sequence: the value of
@code{meta-prefix-char}, followed by the corresponding non-meta
character. Thus, the first example below is handled by conversion into
defined as the @code{backward-word} command. However, if you set
@code{meta-prefix-char} to 24, the code for @kbd{C-x}, then Emacs will
translate @kbd{M-b} into @kbd{C-x b}, whose standard binding is the
-@code{switch-to-buffer} command.
+@code{switch-to-buffer} command. Here is an illustration:
@smallexample
@group
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}.
-
- One advantage of using a list to represent the event type is that the
-precise numeric codes for the modifier bits don't appear in compiled
-files.
+@code{C-H-left}. One advantage of such lists is that the precise
+numeric codes for the modifier bits don't appear in compiled files.
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
@cindex invalid prefix key error
@cindex key sequence error
-Every prefix of @var{key} must be a prefix key (i.e., bound to a
-keymap) or undefined; otherwise an error is signaled.
-
-If some prefix of @var{key} is undefined, then @code{define-key} defines
-it as a prefix key so that the rest of @var{key} may be defined as
-specified.
+Every prefix of @var{key} must be a prefix key (i.e., bound to a keymap)
+or undefined; otherwise an error is signaled. If some prefix of
+@var{key} is undefined, then @code{define-key} defines it as a prefix
+key so that the rest of @var{key} can be defined as specified.
If there was previously no binding for @var{key} in @var{keymap}, the
new binding is added at the beginning of @var{keymap}. The order of
@end smallexample
@noindent
-These are not all the keymaps you would see in an actual case.
+These are not all the keymaps you would see in actuality.
@end defun
@defun where-is-internal command &optional keymap firstonly noindirect
@end defun
@deffn Command describe-bindings prefix
-This function creates a listing of all defined keys and their
-definitions. It writes the listing in a buffer named @samp{*Help*} and
-displays it in a window.
+This function creates a listing of all current key bindings, and
+displays it in a buffer named @samp{*Help*}. The text is grouped by
+modes---minor modes first, then the major mode, then global bindings.
If @var{prefix} is non-@code{nil}, it should be a prefix key; then the
listing includes only keys that start with @var{prefix}.
an existing menu, you can specify its position in the menu using
@code{define-key-after} (@pxref{Modifying Menus}).
-The individual bindings in the menu keymap should have item
-strings; these strings become the items displayed in the menu. A
-binding with an item string looks like this:
+@menu
+* Simple Menu Items::
+* Extended Menu Items::
+@end menu
+
+@node Simple Menu Items
+@subsubsection Simple Menu Items
+
+ The simpler and older way to define a menu keymap binding
+looks like this:
@example
-(@var{string} . @var{real-binding})
+(@var{item-string} . @var{real-binding})
@end example
-The item string for a binding should be short---one or two words. It
-should describe the action of the command it corresponds to.
+The @sc{car}, @var{item-string}, is the string to be displayed in the
+menu. It should be short---preferably one to three words. It should
+describe the action of the command it corresponds to.
You can also supply a second string, called the help string, as follows:
@example
-(@var{string} @var{help-string} . @var{real-binding})
+(@var{item-string} @var{help-string} . @var{real-binding})
@end example
Currently Emacs does not actually use @var{help-string}; it knows only
In the future we may use @var{help-string} as extended documentation for
the menu item, available on request.
-As far as @code{define-key} is concerned, @var{string} and
+As far as @code{define-key} is concerned, @var{item-string} and
@var{help-string} are part of the event's binding. However,
@code{lookup-key} returns just @var{real-binding}, and only
@var{real-binding} is used for executing the key.
-If @var{real-binding} is @code{nil}, then @var{string} appears in the
-menu but cannot be selected.
+If @var{real-binding} is @code{nil}, then @var{item-string} appears in
+the menu but cannot be selected.
If @var{real-binding} is a symbol and has a non-@code{nil}
@code{menu-enable} property, that property is an expression that
used to display a menu, Emacs evaluates the expression, and it enables
the menu item only if the expression's value is non-@code{nil}. When a
menu item is disabled, it is displayed in a ``fuzzy'' fashion, and
-cannot be selected with the mouse.
+cannot be selected.
The menu bar does not recalculate which items are enabled every time you
look at a menu. This is because the X toolkit requires the whole tree
@c This line is not too long--rms.
@example
-(@var{string} @r{[}@var{help-string}@r{]} (@var{key-binding-data}) . @var{real-binding})
+(@var{item-string} @r{[}@var{help-string}@r{]} (@var{key-binding-data}) . @var{real-binding})
@end example
+@noindent
Don't put these sublists in the menu item yourself; menu display
-calculates them automatically. Don't add keyboard equivalents to the
-item strings in a mouse menu, since that is redundant.
+calculates them automatically. Don't mention keyboard equivalents in
+the item strings themselves, since that is redundant.
Sometimes it is useful to make menu items that use the ``same'' command
but with different enable conditions. You can do this by defining alias
causes menu items for @code{make-read-only} and @code{make-writable} to
show the keyboard bindings for @code{toggle-read-only}.
+@node Extended Menu Items
+@subsubsection Extended Menu Items
+
+ An extended-format menu item is a more flexible and also cleaner
+alternative to the simple format. It consists of a list that starts
+with the symbol @code{menu-item}. To define a non-selectable string,
+the item looks like this:
+
+@example
+(menu-item @var{item-name})
+@end example
+
+@noindent
+where a string consisting of two or more dashes specifies a separator line.
+
+ To define a real menu item which can be selected, the extended format
+item looks like this:
+
+@example
+(menu-item @var{item-name} @var{real-binding}
+ . @var{item-property-list})
+@end example
+
+@noindent
+Here, @var{item-name} is an expression which evaluates to the menu item
+string. Thus, the string need not be a constant. The third element,
+@var{real-binding}, is the command to execute. The tail of the list,
+@var{item-property-list}, has the form of a property list which contains
+other information. Here is a table of the properties that are supported:
+
+@table @code
+@item :enable FORM
+The result of evaluating @var{form} determines whether the item is
+enabled (non-@code{nil} means yes).
+
+@item :visible FORM
+The result of evaluating @var{form} determines whether the item should
+actually appear in the menu (non-@code{nil} means yes). If the item
+does not appear, then the menu is displayed as if this item were
+not defined at all.
+
+@item :help @var{help}
+The value of this property, @var{help}, is the extra help string (not
+currently used).
+
+@item :button (@var{type} . @var{selected})
+This property provides a way to define radio buttons and toggle buttons.
+The @sc{car}, @var{type}, says which: is should be @code{:toggle} or
+@code{:radio}. The @sc{cdr}, @var{selected}, should be a form; the
+result of evaluating it says whether this button is currently selected.
+
+@item :filter @var{filter-fn}
+This property provides a way to compute the menu item dynamically.
+The property value @var{filter-fn} should be a function of one argument;
+when it is called, its argument will be @var{real-binding}. The
+function should return the binding to use instead.
+@end table
+
@node Mouse Menus
@subsection Menus and the Mouse
-The way to make a menu keymap produce a menu is to make it the
-definition of a prefix key.
+ The usual way to make a menu keymap produce a menu is to make it the
+definition of a prefix key. (A Lisp program can explicitly pop up a
+menu and receive the user's choice---see @ref{Pop-Up Menus}.)
-If the prefix key ends with a mouse event, Emacs handles the menu keymap
+ If the prefix key ends with a mouse event, Emacs handles the menu keymap
by popping up a visible menu, so that the user can select a choice with
the mouse. When the user clicks on a menu item, the event generated is
whatever character or symbol has the binding that brought about that
menu item. (A menu item may generate a series of events if the menu has
multiple levels or comes from the menu bar.)
-It's often best to use a button-down event to trigger the menu. Then
+ It's often best to use a button-down event to trigger the menu. Then
the user can select a menu item by releasing the button.
-A single keymap can appear as multiple menu panes, if you explicitly
+ A single keymap can appear as multiple menu panes, if you explicitly
arrange for this. The way to do this is to make a keymap for each pane,
then create a binding for each of those maps in the main keymap of the
menu. Give each of these bindings an item string that starts with
which appears along with the other panes explicitly created for the
submaps.
-X toolkit menus don't have panes; instead, they can have submenus.
+ X toolkit menus don't have panes; instead, they can have submenus.
Every nested keymap becomes a submenu, whether the item string starts
with @samp{@@} or not. In a toolkit version of Emacs, the only thing
special about @samp{@@} at the beginning of an item string is that the
@samp{@@} doesn't appear in the menu item.
-You can also get multiple panes from separate keymaps. The full
-definition of a prefix key always comes from merging the definitions
-supplied by the various active keymaps (minor mode, local, and
-global). When more than one of these keymaps is a menu, each of them
-makes a separate pane or panes. @xref{Active Keymaps}.
-
-In toolkit versions of Emacs, menus don't have panes, so submenus are
-used to represent the separate keymaps. Each keymap's contribution
-becomes one submenu.
-
-A Lisp program can explicitly pop up a menu and receive the user's
-choice. You can use keymaps for this also. @xref{Pop-Up Menus}.
+ You can also produce multiple panes or submenus from separate keymaps.
+The full definition of a prefix key always comes from merging the
+definitions supplied by the various active keymaps (minor mode, local,
+and global). When more than one of these keymaps is a menu, each of
+them makes a separate pane or panes (when Emacs does not use an
+X-toolkit) or a separate submenu (when using an X-toolkit).
+@xref{Active Keymaps}.
@node Keyboard Menus
@subsection Menus and the Keyboard
(defvar menu-bar-print-menu (make-sparse-keymap "Print"))
@end example
- Next we define the menu items:
+@noindent
+Next we define the menu items:
@example
(define-key menu-bar-print-menu [ps-print-region]
command.
If you wanted to attach the same print menu to a mouse click, you
-might do it this way:
+can do it this way:
@example
(define-key global-map [C-S-down-mouse-1] menu-bar-print-menu)
When more than one active keymap defines the same fake function key
for the menu bar, the item appears just once. If the user clicks on
-that menu bar item, it brings up a single, combined submenu containing
+that menu bar item, it brings up a single, combined menu containing
all the subcommands of that item---the global subcommands, the local
-subcommands, and the minor mode subcommands, all together.
+subcommands, and the minor mode subcommands.
The variable @code{overriding-local-map} is normally ignored when
determining the menu bar contents. That is, the menu bar is computed
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
serve to separate the menu bar from the windows in the frame. We
-recommend 1 or 2 as the value of @code{menu-bar-lines}. @xref{X Frame
+recommend 1 or 2 as the value of @code{menu-bar-lines}. @xref{Window Frame
Parameters}.
Here's an example of setting up a menu bar item:
@end group
@group
-;; @r{Define specific subcommands in the item's menu.}
+;; @r{Define specific subcommands in this menu.}
(define-key global-map
[menu-bar words forward]
'("Forward word" . forward-word))
This variable holds a list of fake function keys for items to display at
the end of the menu bar rather than in normal sequence. The default
-value is @code{(help)}; thus, the @samp{Help} menu item normally appears
+value is @code{(help-menu)}; thus, the @samp{Help} menu item normally appears
at the end of the menu bar, following local menu items.
@end defvar
just like @code{define-key}, but position the binding in @var{map} after
the binding for the event @var{after}. The argument @var{key} should be
of length one---a vector or string with just one element. But
-@var{after} should be an event type---a symbol or a character.
+@var{after} should be a single event type---a symbol or a character, not
+a sequence. The new binding goes after the binding for @var{after}. If
+@var{after} is @code{t}, then the new binding goes last, at the end of
+the keymap.
-For example,
+Here is an example:
@example
(define-key-after my-menu [drink]
@end example
@noindent
-makes a binding for the fake function key @key{drink} and puts it
-right after the binding for @key{eat}.
-
-If @var{after} is @code{t}, then the new binding goes last---at the end
-of the keymap.
+makes a binding for the fake function key @key{DRINK} and puts it
+right after the binding for @key{EAT}.
Here is how to insert an item called @samp{Work} in the @samp{Signals}
menu of Shell mode, after the item @code{break}:
(lookup-key shell-mode-map [menu-bar signals])
[work] '("Work" . work-command) 'break)
@end example
-
-Note that @var{key} is a sequence containing just one event type, but
-@var{after} is just an event type (not a sequence).
@end defun
@example
@group
- ___ ___ ___ ___
- |___|___|--> |___|___|--> nil
+ --- --- --- ---
+ | | |--> | | |--> nil
+ --- --- --- ---
| |
| |
--> tulip --> lily
@example
@group
- ___ ___ ___ ___ ___ ___
- |___|___|--> |___|___|--> |___|___|--> nil
+ --- --- --- --- --- ---
+ | | |--> | | |--> | | |--> nil
+ --- --- --- --- --- ---
| | |
| | |
| --> oak --> maple
|
- | ___ ___ ___ ___
- --> |___|___|--> |___|___|--> nil
+ | --- --- --- ---
+ --> | | |--> | | |--> nil
+ --- --- --- ---
| |
| |
--> pine --> needles
(nth n x) @equiv{} (car (nthcdr n x))
@end group
@end example
+
+The function @code{elt} is similar, but applies to any kind of sequence.
+For historical reasons, it takes its arguments in the opposite order.
+@xref{Sequence Functions}.
@end defun
@defun nthcdr n list
@end defun
@tindex safe-length
-@defun safe-length sequence
+@defun safe-length list
This function returns the length of @var{list}, with no risk
of either an error or an infinite loop.
number of distinct elements.
@end defun
+ The most common way to compute the length of a list, when you are not
+worried that it may be circular, is with @code{length}. @xref{Sequence
+Functions}.
+
@tindex caar
-@defun caar list
-This is the same as @code{(car (car @var{list}))}.
+@defun caar cons-cell
+This is the same as @code{(car (car @var{cons-cell}))}.
@end defun
@tindex cadr
-@defun cadr list
-This is the same as @code{(car (cdr @var{list}))}
-or @code{(nth 1 @var{list})}.
+@defun cadr cons-cell
+This is the same as @code{(car (cdr @var{cons-cell}))}
+or @code{(nth 1 @var{cons-cell})}.
@end defun
@tindex cdar
-@defun cdar list
-This is the same as @code{(cdr (car @var{list}))}.
+@defun cdar cons-cell
+This is the same as @code{(cdr (car @var{cons-cell}))}.
@end defun
@tindex cddr
-@defun cddr list
-This is the same as @code{(cdr (cdr @var{list}))}
-or @code{(nthcdr 2 @var{list})}.
+@defun cddr cons-cell
+This is the same as @code{(cdr (cdr @var{cons-cell}))}
+or @code{(nthcdr 2 @var{cons-cell})}.
@end defun
@node Building Lists
@defun append &rest sequences
@cindex copying lists
This function returns a list containing all the elements of
-@var{sequences}. The @var{sequences} may be lists, vectors, or strings,
-but the last one should usually be a list. All arguments except the
-last one are copied, so none of the arguments is altered.
+@var{sequences}. The @var{sequences} may be lists, vectors,
+bool-vectors, or strings, but the last one should usually be a list.
+All arguments except the last one are copied, so none of the arguments
+is altered. (See @code{nconc} in @ref{Rearrangement}, for a way to join
+lists with no copying.)
More generally, the final argument to @code{append} may be any Lisp
object. The final argument is not copied or converted; it becomes the
``dotted list'' since its final @sc{cdr} is not @code{nil} as required
in a true list.
-See @code{nconc} in @ref{Rearrangement}, for a way to join lists with no
-copying.
-
Here is an example of using @code{append}:
@example
@group
more-trees trees
| |
-| ___ ___ ___ ___ -> ___ ___ ___ ___
- --> |___|___|--> |___|___|--> |___|___|--> |___|___|--> nil
+| --- --- --- --- -> --- --- --- ---
+ --> | | |--> | | |--> | | |--> | | |--> nil
+ --- --- --- --- --- --- --- ---
| | | |
| | | |
--> maple -->birch --> pine --> oak
@result{} (pine oak)
@end group
@group
-(setq wood (append trees ()))
+(setq wood (append trees nil))
@result{} (pine oak)
@end group
@group
This once was the usual way to copy a list, before the function
@code{copy-sequence} was invented. @xref{Sequences Arrays Vectors}.
+Here we show the use of vectors and strings as arguments to @code{append}:
+
+@example
+@group
+(append [a b] "cd" nil)
+ @result{} (a b 99 100)
+@end group
+@end example
+
With the help of @code{apply}, we can append all the lists in a list of
lists:
@example
@group
- ___ ___ ___ ___ ___ ___
-x1---> |___|___|----> |___|___|--> |___|___|--> nil
+ --- --- --- --- --- ---
+x1---> | | |----> | | |--> | | |--> nil
+ --- --- --- --- --- ---
| --> | |
| | | |
--> a | --> b --> c
|
- ___ ___ |
-x2--> |___|___|--
+ --- --- |
+x2--> | | |--
+ --- ---
|
|
--> z
@end group
@end example
+However, the other arguments (all but the last) must be lists.
+
A common pitfall is to use a quoted constant list as a non-last
argument to @code{nconc}. If you do this, your program will change
each time you run it! Here is what happens:
@end example
The following two functions are like @code{memq} and @code{delq} but use
-@code{equal} rather than @code{eq} to compare elements.
+@code{equal} rather than @code{eq} to compare elements. @xref{Equality
+Predicates}.
@defun member object list
The function @code{member} tests to see whether @var{object} is a member
means you should consider recompiling @file{foo.el}. @xref{Byte
Compilation}.
+When loading a source file (not compiled), @code{load} performs
+character set translation just as Emacs would do when visiting the file.
+@xref{Coding Systems}.
+
Messages like @samp{Loading foo...} and @samp{Loading foo...done} appear
in the echo area during loading unless @var{nomessage} is
non-@code{nil}.
@file{/usr/local/lisplib} directory, and the @file{~/emacs} directory,
which are then followed by the standard directories for Lisp code.
-The command line options @samp{-l} or @samp{-load} specify a Lisp
-library to load as part of Emacs startup. Since this file might be in
-the current directory, Emacs 18 temporarily adds the current directory
-to the front of @code{load-path} so the file can be found there. Newer
-Emacs versions also find such files in the current directory, but
-without altering @code{load-path}.
-
Dumping Emacs uses a special value of @code{load-path}. If the value of
@code{load-path} at the end of dumping is unchanged (that is, still the
same special value), the dumped Emacs switches to the ordinary
functions should use @code{read}.
@end defvar
- To learn how @code{load} is used to build Emacs, see @ref{Building Emacs}.
+ For how @code{load} is used to build Emacs, see @ref{Building Emacs}.
@deffn Command locate-library library &optional nosuffix path interactive-call
This command finds the precise file name for library @var{library}. It
@code{autoload}, and by writing a special ``magic'' comment in the
source before the real definition. @code{autoload} is the low-level
primitive for autoloading; any Lisp program can call @code{autoload} at
-any time. Magic comments do nothing on their own; they serve as a guide
-for the command @code{update-file-autoloads}, which constructs calls to
-@code{autoload} and arranges to execute them when Emacs is built. Magic
-comments are the most convenient way to make a function autoload, but
-only for packages installed along with Emacs.
+any time. Magic comments are the most convenient way to make a function
+autoload, for packages installed along with Emacs. They do nothing on
+their own, but they serve as a guide for the command
+@code{update-file-autoloads}, which constructs calls to @code{autoload}
+and arranges to execute them when Emacs is built.
@defun autoload function filename &optional docstring interactive type
This function defines the function (or macro) named @var{function} so as
in the call to @code{autoload} makes it possible to look at the
documentation without loading the function's real definition.
-If @var{interactive} is non-@code{nil}, then the function can be called
-interactively. This lets completion in @kbd{M-x} work without loading
-the function's real definition. The complete interactive specification
-is not given here; it's not needed unless the user actually calls
+If @var{interactive} is non-@code{nil}, that says @var{function} can be
+called interactively. This lets completion in @kbd{M-x} work without
+loading its real definition. The complete interactive specification is
+not given here; it's not needed unless the user actually calls
@var{function}, and when that happens, it's time to load the real
definition.
comment to execute a form at build time @emph{without} executing it when
the file itself is loaded. To do this, write the form @emph{on the same
line} as the magic comment. Since it is in a comment, it does nothing
-when you load the source file; but @code{update-file-autoloads} copies
-it to @file{loaddefs.el}, where it is executed while building Emacs.
+when you load the source file; but @kbd{M-x update-file-autoloads}
+copies it to @file{loaddefs.el}, where it is executed while building
+Emacs.
The following example shows how @code{doctor} is prepared for
autoloading with a magic comment:
@section Repeated Loading
@cindex repeated loading
- You may load one file more than once in an Emacs session. For
+ You can load one file more than once in an Emacs session. For
example, after you have rewritten and reinstalled a function definition
by editing it in a buffer, you may wish to return to the original
version; you can do this by reloading the file it came from.
that you intend to save and reinstall, you need to byte-compile the new
version; otherwise Emacs will load the older, byte-compiled file instead
of your newer, non-compiled file! If that happens, the message
-displayed when loading the file says, ``(compiled; source is newer'', to
-remind you to recompile.
+displayed when loading the file includes, @samp{(compiled; source is
+newer)}, to remind you to recompile it.
When writing the forms in a Lisp library file, keep in mind that the
file might be loaded more than once. For example, think about whether
has been loaded before:
@example
-(defvar foo-was-loaded)
+(defvar foo-was-loaded nil)
-(if (not (boundp 'foo-was-loaded))
- @var{execute-first-time-only})
-
-(setq foo-was-loaded t)
+(unless foo-was-loaded
+ @var{execute-first-time-only}
+ (setq foo-was-loaded t))
@end example
@noindent
If the library uses @code{provide} to provide a named feature, you can
-use @code{featurep} to test whether the library has been loaded.
+use @code{featurep} earlier in the file to test whether the
+@code{provide} call has been executed before.
@ifinfo
@xref{Named Features}.
@end ifinfo
@code{features}; if it fails to do so, @code{require} signals an error.
@cindex load error with require
- Features are normally named after the files that provide them, so that
-@code{require} need not be given the file name.
-
For example, in @file{emacs/lisp/prolog.el},
the definition for @code{run-prolog} includes the following code:
@noindent
The expression @code{(require 'comint)} loads the file @file{comint.el}
if it has not yet been loaded. This ensures that @code{make-comint} is
-defined.
+defined. Features are normally named after the files that provide them,
+so that @code{require} need not be given the file name.
The @file{comint.el} file contains the following top-level expression:
The compiler ignores the @code{provide}, then processes the
@code{require} by loading the file in question. Loading the file does
execute the @code{provide} call, so the subsequent @code{require} call
-does nothing while loading.
+does nothing when the file is loaded.
@defun provide feature
This function announces that @var{feature} is now loaded, or being
@defun featurep feature
This function returns @code{t} if @var{feature} has been provided in the
-current Emacs session (i.e., @var{feature} is a member of
+current Emacs session (i.e., if @var{feature} is a member of
@code{features}.)
@end defun
@deffn Command unload-feature feature &optional force
This command unloads the library that provided feature @var{feature}.
It undefines all functions, macros, and variables defined in that
-library with @code{defconst}, @code{defvar}, @code{defun},
-@code{defmacro}, @code{defsubst} and @code{defalias}. It then restores
-any autoloads formerly associated with those symbols. (Loading
-saves these in the @code{autoload} property of the symbol.)
+library with @code{defun}, @code{defalias}, @code{defsubst},
+@code{defmacro}, @code{defconst}, @code{defvar}, and @code{defcustom}.
+It then restores any autoloads formerly associated with those symbols.
+(Loading saves these in the @code{autoload} property of the symbol.)
Ordinarily, @code{unload-feature} refuses to unload a library on which
other loaded libraries depend. (A library @var{a} depends on library
the library is loaded. To do (2), you must load the library (preferably
with @code{require}).
-But it is ok to use @code{eval-after-load} in your personal customizations
-if you don't feel they must meet the design standards of programs to be
-released.
+But it is OK to use @code{eval-after-load} in your personal
+customizations if you don't feel they must meet the design standards for
+programs meant for wider use.
@defvar after-load-alist
An alist of expressions to evaluate if and when particular libraries are
@c The title "Standard Buffer-Local Variables" is too long for
@c smallbook. --rjc 30mar92
- The table below lists the general-purpose Emacs variables that are
-automatically local (when set) in each buffer. Many Lisp packages
-define such variables for their internal use; we don't list them here.
+ The table below lists the general-purpose Emacs variables that
+automatically become buffer-local in each buffer. Most become
+buffer-local only when set; a few of them are always local in every
+buffer. Many Lisp packages define such variables for their internal
+use, but we don't try to list them all here.
@table @code
@item abbrev-mode
-@pxref{Abbrevs}
+@xref{Abbrevs}.
@item auto-fill-function
-@pxref{Auto Filling}
+@xref{Auto Filling}.
@item buffer-auto-save-file-name
-@pxref{Auto-Saving}
+@xref{Auto-Saving}.
@item buffer-backed-up
-@pxref{Backup Files}
+@xref{Backup Files}.
+
+@item buffer-display-count
+@xref{Displaying Buffers}.
@item buffer-display-table
-@pxref{Display Tables}
+@xref{Display Tables}.
@item buffer-file-format
-@pxref{Format Conversion}
+@xref{Format Conversion}.
@item buffer-file-name
-@pxref{Buffer File Name}
+@xref{Buffer File Name}.
@item buffer-file-number
-@pxref{Buffer File Name}
+@xref{Buffer File Name}.
@item buffer-file-truename
-@pxref{Buffer File Name}
+@xref{Buffer File Name}.
@item buffer-file-type
-@pxref{Files and MS-DOS}
+@xref{MS-DOS File Types}.
@item buffer-invisibility-spec
-@pxref{Invisible Text}
+@xref{Invisible Text}.
@item buffer-offer-save
-@pxref{Saving Buffers}
+@xref{Saving Buffers}.
@item buffer-read-only
-@pxref{Read Only Buffers}
+@xref{Read Only Buffers}.
@item buffer-saved-size
-@pxref{Point}
+@xref{Point}.
@item buffer-undo-list
-@pxref{Undo}
+@xref{Undo}.
@item cache-long-line-scans
-@pxref{Text Lines}
+@xref{Text Lines}.
@item case-fold-search
-@pxref{Searching and Case}
+@xref{Searching and Case}.
@item ctl-arrow
-@pxref{Usual Display}
+@xref{Usual Display}.
@item comment-column
-@pxref{Comments,,, emacs, The GNU Emacs Manual}
+@xref{Comments,,, emacs, The GNU Emacs Manual}.
@item default-directory
-@pxref{System Environment}
+@xref{System Environment}.
@item defun-prompt-regexp
-@pxref{List Motion}
+@xref{List Motion}.
+
+@item enable-multibyte-characters
+@ref{Non-ASCII Characters}.
@item fill-column
-@pxref{Auto Filling}
+@xref{Auto Filling}.
@item goal-column
-@pxref{Moving Point,,, emacs, The GNU Emacs Manual}
+@xref{Moving Point,,, emacs, The GNU Emacs Manual}.
@item left-margin
-@pxref{Indentation}
+@xref{Indentation}.
@item local-abbrev-table
-@pxref{Abbrevs}
+@xref{Abbrevs}.
@item local-write-file-hooks
-@pxref{Saving Buffers}
+@xref{Saving Buffers}.
@item major-mode
-@pxref{Mode Help}
+@xref{Mode Help}.
@item mark-active
-@pxref{The Mark}
+@xref{The Mark}.
@item mark-ring
-@pxref{The Mark}
+@xref{The Mark}.
@item minor-modes
-@pxref{Minor Modes}
+@xref{Minor Modes}.
@item mode-line-buffer-identification
-@pxref{Mode Line Variables}
+@xref{Mode Line Variables}.
@item mode-line-format
-@pxref{Mode Line Data}
+@xref{Mode Line Data}.
@item mode-line-modified
-@pxref{Mode Line Variables}
+@xref{Mode Line Variables}.
@item mode-line-process
-@pxref{Mode Line Variables}
+@xref{Mode Line Variables}.
@item mode-name
-@pxref{Mode Line Variables}
+@xref{Mode Line Variables}.
@item overwrite-mode
-@pxref{Insertion}
+@xref{Insertion}.
@item paragraph-separate
-@pxref{Standard Regexps}
+@xref{Standard Regexps}.
@item paragraph-start
-@pxref{Standard Regexps}
+@xref{Standard Regexps}.
@item point-before-scroll
-Used for communication between mouse commands and scroll-bar commands.
+Ued for communication between mouse commands and scroll-bar commands..
@item require-final-newline
-@pxref{Insertion}
+@xref{Insertion}.
@item selective-display
-@pxref{Selective Display}
+@xref{Selective Display}.
@item selective-display-ellipses
-@pxref{Selective Display}
+@xref{Selective Display}.
@item tab-width
-@pxref{Usual Display}
+@xref{Usual Display}.
@item truncate-lines
-@pxref{Truncation}
+@xref{Truncation}.
@item vc-mode
-@pxref{Mode Line Variables}
+@xref{Mode Line Variables}.
@end table
@end group
@end example
- When this is called with @code{(inc x)}, the argument @code{var} has
-the value @code{x}---@emph{not} the @emph{value} of @code{x}. The body
-of the macro uses this to construct the expansion, which is @code{(setq
-x (1+ x))}. Once the macro definition returns this expansion, Lisp
-proceeds to evaluate it, thus incrementing @code{x}.
+ When this is called with @code{(inc x)}, the argument @var{var} is the
+symbol @code{x}---@emph{not} the @emph{value} of @code{x}, as it would
+be in a function. The body of the macro uses this to construct the
+expansion, which is @code{(setq x (1+ x))}. Once the macro definition
+returns this expansion, Lisp proceeds to evaluate it, thus incrementing
+@code{x}.
@node Expansion
@section Expansion of a Macro Call
(macro lambda @var{argument-list} . @var{body-forms})
@end example
+(Note that the @sc{cdr} of this list is a function---a lambda expression.)
This macro object is stored in the function cell of @var{name}. The
value returned by evaluating the @code{defmacro} form is @var{name}, but
usually we ignore this value.
@findex `
Macros often need to construct large list structures from a mixture of
-constants and nonconstant parts. To make this easier, use the macro
-@samp{`} (often called @dfn{backquote}).
+constants and nonconstant parts. To make this easier, use the @samp{`}
+syntax (usually called @dfn{backquote}).
Backquote allows you to quote a list, but selectively evaluate
elements of that list. In the simplest case, it is identical to the
@end group
@end example
-@quotation
-Before Emacs version 19.29, @samp{`} used a different syntax which
-required an extra level of parentheses around the entire backquote
-construct. Likewise, each @samp{,} or @samp{,@@} substition required an
-extra level of parentheses surrounding both the @samp{,} or @samp{,@@}
-and the following expression. The old syntax required whitespace
-between the @samp{`}, @samp{,} or @samp{,@@} and the following
-expression.
+In old Emacs versions, before version 19.29, @samp{`} used a different
+syntax which required an extra level of parentheses around the entire
+backquote construct. Likewise, each @samp{,} or @samp{,@@} substitution
+required an extra level of parentheses surrounding both the @samp{,} or
+@samp{,@@} and the following expression. The old syntax required
+whitespace between the @samp{`}, @samp{,} or @samp{,@@} and the
+following expression.
This syntax is still accepted, for compatibility with old Emacs
versions, but we recommend not using it in new programs.
-@end quotation
@node Problems with Macros
@section Common Problems Using Macros
@end smallexample
@noindent
-(The arguments @code{from}, @code{to}, and @code{do} in this macro are
+The arguments @code{from}, @code{to}, and @code{do} in this macro are
``syntactic sugar''; they are entirely ignored. The idea is that you
will write noise words (such as @code{from}, @code{to}, and @code{do})
-in those positions in the macro call.)
+in those positions in the macro call.
Here's an equivalent definition simplified through use of backquote:
@end group
@end smallexample
- Unfortunately, this introduces another problem.
-@ifinfo
-Proceed to the following node.
-@end ifinfo
+ Unfortunately, this fix introduces another problem,
+described in the following section.
@node Surprising Local Vars
@subsection Local Variables in Macro Expansions
@code{x}, because @code{a} conflicts with the macro argument variable
@code{a}.
- Another reason not to call @code{eval} in a macro definition is that
+ Another problem with calling @code{eval} in a macro definition is that
it probably won't do what you intend in a compiled program. The
byte-compiler runs macro definitions while compiling the program, when
the program's own computations (which you might have wished to access
with @code{eval}) don't occur and its local variable bindings don't
exist.
- The safe way to work with the run-time value of an expression is to
-put the expression into the macro expansion, so that its value is
-computed as part of executing the expansion. This is what the other
-examples in this chapter do.
+ To avoid these problems, @strong{don't evaluate an argument expression
+while computing the macro expansion.} Instead, substitute the
+expression into the macro expansion, so that its value will be computed
+as part of executing the expansion. This is how the other examples in
+this chapter work.
@node Repeated Expansion
@subsection How Many Times is the Macro Expanded?
macro definition has side effects, they will work differently depending
on how many times the macro is expanded.
- In particular, constructing objects is a kind of side effect. If the
-macro is called once, then the objects are constructed only once. In
-other words, the same structure of objects is used each time the macro
-call is executed. In interpreted operation, the macro is reexpanded
-each time, producing a fresh collection of objects each time. Usually
-this does not matter---the objects have the same contents whether they
-are shared or not. But if the surrounding program does side effects
-on the objects, it makes a difference whether they are shared. Here is
-an example:
+ Therefore, you should avoid side effects in computation of the
+macro expansion, unless you really know what you are doing.
+
+ One special kind of side effect can't be avoided: constructing Lisp
+objects. Almost all macro expansions include constructed lists; that is
+the whole point of most macros. This is usually safe; there is just one
+case where you must be careful: when the object you construct is part of a
+quoted constant in the macro expansion.
+
+ If the macro is expanded just once, in compilation, then the object is
+constructed just once, during compilation. But in interpreted
+execution, the macro is expanded each time the macro call runs, and this
+means a new object is constructed each time.
+
+ In most clean Lisp code, this difference won't matter. It can matter
+only if you perform side-effects on the objects constructed by the macro
+definition. Thus, to avoid trouble, @strong{avoid side effects on
+objects constructed by macro definitions}. Here is an example of how
+such side effects can get you into trouble:
@lisp
@group
A full keymap used by Command History mode.
@item ctl-x-4-map
-@vindex ctl-x-4-map
A sparse keymap for subcommands of the prefix @kbd{C-x 4}.
@item ctl-x-5-map
-@vindex ctl-x-5-map
A sparse keymap for subcommands of the prefix @kbd{C-x 5}.
@item ctl-x-map
-@vindex ctl-x-map
A full keymap for @kbd{C-x} commands.
@item debugger-mode-map
Properties menu.
@item function-key-map
-@vindex function-key-map
The keymap for translating keypad and function keys.@*
If there are none, then it contains an empty sparse keymap.
+@xref{Translating Input}.
@item fundamental-mode-map
@vindex fundamental-mode-map
search.
@item key-translation-map
-@vindex key-translation-map
A keymap for translating keys. This one overrides ordinary key
-bindings, unlike @code{function-key-map}.
+bindings, unlike @code{function-key-map}. @xref{Translating Input}.
@item lisp-interaction-mode-map
@vindex lisp-interaction-mode-map
@vindex menu-bar-help-menu
The keymap which displays the Help menu in the menu bar.
+@tindex menu-bar-mule-menu
+@item menu-bar-mule-menu
+@vindex menu-bar-mule-menu
+The keymap which displays the Mule menu in the menu bar.
+
@item menu-bar-search-menu
@vindex menu-bar-search-menu
The keymap which displays the Search menu in the menu bar.
The keymap which displays the Tools menu in the menu bar.
@item mode-specific-map
-@vindex mode-specific-map
The keymap for characters following @kbd{C-c}. Note, this is in the
global map. This map is not actually mode specific: its name was chosen
to be informative for the user in @kbd{C-h b} (@code{display-bindings}),
A local keymap used by Occur mode.
@item query-replace-map
-@vindex query-replace-map
A local keymap used for responses in @code{query-replace} and related
commands; also for @code{y-or-n-p} and @code{map-y-or-n-p}. The functions
that use this map do not support prefix keys; they look up one event at a
@cindex marker relocation
Deleting text around a marker's position leaves the marker between the
characters immediately before and after the deleted text. Inserting
-text at the position of a marker normally leaves the marker in front of
-the new text---unless it is inserted with @code{insert-before-markers}
-(@pxref{Insertion}).
+text at the position of a marker normally leaves the marker either in
+front of or after the new text, depending on the marker's @dfn{insertion
+type} (@pxref{Marker Insertion Types})---unless the insertion is done
+with @code{insert-before-markers} (@pxref{Insertion}).
@cindex marker garbage collection
Insertion and deletion in a buffer must check all the markers and
When you insert text directly at the place where a marker points,
there are two possible ways to relocate that marker: it can point before
the inserted text, or point after it. You can specify which one a given
-marker should do by setting its @dfn{insertion type}.
+marker should do by setting its @dfn{insertion type}. Note that use of
+@code{insert-before-markers} ignores markers' insertion types, always
+relocating a marker to point after the inserted text.
@tindex set-marker-insertion-type
@defun set-marker-insertion-type marker type
Once the mark ``exists'' in a buffer, it normally never ceases to
exist. However, it may become @dfn{inactive}, if Transient Mark mode is
-enabled. The variable @code{mark-active}, which is always local in all
-buffers, indicates whether the mark is active: non-@code{nil} means yes.
-A command can request deactivation of the mark upon return to the editor
-command loop by setting @code{deactivate-mark} to a non-@code{nil} value
-(but this causes deactivation only if Transient Mark mode is enabled).
+enabled. The variable @code{mark-active}, which is always buffer-local
+in all buffers, indicates whether the mark is active: non-@code{nil}
+means yes. A command can request deactivation of the mark upon return
+to the editor command loop by setting @code{deactivate-mark} to a
+non-@code{nil} value (but this causes deactivation only if Transient
+Mark mode is enabled).
The main motivation for using Transient Mark mode is that this mode
also enables highlighting of the region when the mark is active.
make the mark inactive.
@end defopt
+@defopt mark-even-if-inactive
+If this is non-@code{nil}, Lisp programs and the Emacs user can use the
+mark even when it is inactive. This option affects the behavior of
+Transient Mark mode. When the option is non-@code{nil}, deactivation of
+the mark turns off region highlighting, but commands that use the mark
+behave as if the mark were still active.
+@end defopt
+
@defvar deactivate-mark
If an editor command sets this variable non-@code{nil}, then the editor
-command loop deactivates the mark after the command returns, but only if
-Transient Mark mode is enabled.
+command loop deactivates the mark after the command returns (if
+Transient Mark mode is enabled). All the primitives that change the
+buffer set @code{deactivate-mark}, to deactivate the mark when the
+command is finished.
@end defvar
@defun deactivate-mark
-This function deactivates the mark, but only if Transient Mark mode
-is enabled.
+This function deactivates the mark, if Transient Mark mode is enabled.
+Otherwise it does nothing.
@end defun
@defvar mark-active
The mark is active when this variable is non-@code{nil}. This variable
-is always local in each buffer.
+is always buffer-local in each buffer.
@end defvar
@defvar activate-mark-hook
arguments more complicated than the single numeric prefix argument.
These arguments include file names, buffer names, and command names (as
in @kbd{M-x}). The minibuffer is displayed on the bottom line of the
-screen, in the same place as the echo area, but only while it is in
-use for reading an argument.
+frame, in the same place as the echo area, but only while it is in use
+for reading an argument.
@menu
* Intro to Minibuffers:: Basic information about minibuffers.
@code{read} to convert the text into a Lisp object (@pxref{Input
Functions}).
-The first thing this function does is to activate a minibuffer and
+The first thing this function does is to activate a minibuffer and
display it with @var{prompt-string} as the prompt. This value must be a
-string.
-
-Then, if @var{initial-contents} is a string, @code{read-from-minibuffer}
-inserts it into the minibuffer, leaving point at the end. The
-minibuffer appears with this text as its contents.
+string. Then the user can edit text in the minibuffer.
-@strong{Usage note:} The @var{initial-contents} argument and the
-@var{default} argument are two alternative features for the same job.
-It usually does not make sense to use both at once. In most cases, you
-should use @var{default}, since this permits the user to insert the
-default value but does not burden the user with deleting it from the
-minibuffer.
+When the user types a command to exit the minibuffer,
+@code{read-from-minibuffer} constructs the return value from the text in
+the minibuffer. Normally it returns a string containing that text.
+However, if @var{read} is non-@code{nil}, @code{read-from-minibuffer}
+reads the text and returns the resulting Lisp object, unevaluated.
+(@xref{Input Functions}, for information about reading.)
-@c Emacs 19 feature
-The value of @var{initial-contents} may also be a cons cell of the form
-@code{(@var{string} . @var{position})}. This means to insert
-@var{string} in the minibuffer but put point @var{position} characters
-from the beginning, rather than at the end.
+The argument @var{default} specifies a default value to make available
+through the history commands. It should be a string, or @code{nil}. If
+@var{read} is non-@code{nil}, then @var{default} is also used as the
+input to @code{read}, if the user enters empty input. However, in the
+usual case (where @var{read} is @code{nil}, @code{read-from-minibuffer}
+does not return @var{default} when the user enters empty input; it
+returns an empty string, @code{""}. In this respect, it is different
+from all the other minibuffer input functions in this chapter.
If @var{keymap} is non-@code{nil}, that keymap is the local keymap to
use in the minibuffer. If @var{keymap} is omitted or @code{nil}, the
for saving the input and for history commands used in the minibuffer.
It defaults to @code{minibuffer-history}. @xref{Minibuffer History}.
-When the user types a command to exit the minibuffer,
-@code{read-from-minibuffer} uses the text in the minibuffer to produce
-its return value. Normally it simply makes a string containing that
-text. However, if @var{read} is non-@code{nil},
-@code{read-from-minibuffer} reads the text and returns the resulting
-Lisp object, unevaluated. (@xref{Input Functions}, for information
-about reading.)
-
If the variable @code{minibuffer-allow-text-properties} is
non-@code{nil}, then the string which is returned includes whatever text
properties were present in the minibuffer. Otherwise all the text
properties are stripped when the value is returned.
-The argument @var{default} specifies a default value to make available
-through the history list. It should be a string, or @code{nil}. If
-@var{read} is non-@code{nil}, then @var{default} is passed through
-@code{read}, just as ordinary user input would be. Unlike many other
-minibuffer functions, this function does @emph{not} return @var{default}
-if the user enters empty input. It returns @code{""} in that case.
-
If the argument @var{inherit-input-method} is non-@code{nil}, then the
minibuffer inherits the current input method and the setting of
@code{enable-multibyte-characters} from whichever buffer was current
before entering the minibuffer.
+
+If @var{initial-contents} is a string, @code{read-from-minibuffer}
+inserts it into the minibuffer, leaving point at the end, before the
+user starts to edit the text. The minibuffer appears with this text as
+its initial contents.
+
+Alternatively, @var{initial-contents} can be a cons cell of the form
+@code{(@var{string} . @var{position})}. This means to insert
+@var{string} in the minibuffer but put point @var{position} characters
+from the beginning, rather than at the end.
+
+@strong{Usage note:} The @var{initial-contents} argument and the
+@var{default} argument are two alternative features for more or less the
+same job. It does not make sense to use both features in a single call
+to @code{read-from-minibuffer}. In general, we recommend using
+@var{default}, since this permits the user to insert the default value
+when it is wanted, but does not burden the user with deleting it from
+the minibuffer on other occasions.
@end defun
@defun read-string prompt &optional initial history default inherit-input-method
@group
(read-string @var{prompt} @var{initial} @var{history} @var{default} @var{inherit})
@equiv{}
-(read-from-minibuffer @var{prompt} @var{initial} nil nil
- @var{history} @var{default} @var{inherit})
+(let ((value
+ (read-from-minibuffer @var{prompt} @var{initial} nil nil
+ @var{history} @var{default} @var{inherit})))
+ (if (equal value "")
+ @var{default}
+ value))
@end group
@end smallexample
@end defun
default, it makes the following bindings:
@table @asis
-@item @key{LFD}
+@item @kbd{C-j}
@code{exit-minibuffer}
@item @key{RET}
@cindex minibuffer history
@cindex history list
-A @dfn{minibuffer history list} records previous minibuffer inputs so
+ A @dfn{minibuffer history list} records previous minibuffer inputs so
the user can reuse them conveniently. A history list is actually a
symbol, not a list; it is a variable whose value is a list of strings
(previous inputs), most recent first.
-There are many separate history lists, used for different kinds of
+ There are many separate history lists, used for different kinds of
inputs. It's the Lisp programmer's job to specify the right history
list for each use of the minibuffer.
-The basic minibuffer input functions @code{read-from-minibuffer} and
+ The basic minibuffer input functions @code{read-from-minibuffer} and
@code{completing-read} both accept an optional argument named @var{hist}
which is how you specify the history list. Here are the possible
values:
of the history as the initial minibuffer contents, for consistency.
@end table
-If you don't specify @var{hist}, then the default history list
+ If you don't specify @var{hist}, then the default history list
@code{minibuffer-history} is used. For other standard history lists,
see below. You can also create your own history list variable; just
initialize it to @code{nil} before the first use.
-Both @code{read-from-minibuffer} and @code{completing-read} add new
+ Both @code{read-from-minibuffer} and @code{completing-read} add new
elements to the history list automatically, and provide commands to
allow the user to reuse items on the list. The only thing your program
needs to do to use a history list is to initialize it and to pass its
name to the input functions when you wish. But it is safe to modify the
list by hand when the minibuffer input functions are not using it.
+ Here are some of the standard minibuffer history list variables:
+
@defvar minibuffer-history
The default history list for minibuffer history input.
@end defvar
@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
+@var{string}. The arguments to this function are the same as those of
@code{try-completion}.
If @var{collection} is a function, it is called with three arguments:
@defun completing-read prompt collection &optional predicate require-match initial hist default inherit-input-method
This function reads a string in the minibuffer, assisting the user by
providing completion. It activates the minibuffer with prompt
-@var{prompt}, which must be a string. If @var{initial} is
-non-@code{nil}, @code{completing-read} inserts it into the minibuffer as
-part of the input. Then it allows the user to edit the input, providing
-several commands to attempt completion.
+@var{prompt}, which must be a string.
The actual completion is done by passing @var{collection} and
@var{predicate} to the function @code{try-completion}. This happens in
However, empty input is always permitted, regardless of the value of
@var{require-match}; in that case, @code{completing-read} returns
-@var{default}.
+@var{default}. The value of @var{default} (if non-@code{nil}) is also
+available to the user through the history commands.
The user can exit with null input by typing @key{RET} with an empty
minibuffer. Then @code{completing-read} returns @code{""}. This is how
saving the input and for minibuffer history commands. It defaults to
@code{minibuffer-history}. @xref{Minibuffer History}.
-The optional argument @var{default} specifies a default value to return
-if the user enters null input; it should be a string.
+If @var{initial} is non-@code{nil}, @code{completing-read} inserts it
+into the minibuffer as part of the input. Then it allows the user to
+edit the input, providing several commands to attempt completion.
+In most cases, we recommend using @var{default}, and not @var{initial}.
If the argument @var{inherit-input-method} is non-@code{nil}, then the
minibuffer inherits the current input method and the setting of
@item @key{TAB}
@code{minibuffer-complete}
-@item @key{LFD}
+@item @kbd{C-j}
@code{minibuffer-complete-and-exit}
@item @key{RET}
for which @code{commandp} returns @code{t}. @xref{Interactive Call}.
The argument @var{default} specifies what to return if the user enters
-null input. It can be a symbol or a string, but the value returned by
-@code{read-command} is always a symbol. If @var{default} is @code{nil},
-that means no default has been specified; then if the user enters null
-input, the return value is @code{nil}.
+null input. It can be a symbol or a string; if it is a string,
+@code{read-command} interns it before returning it. If @var{default} is
+@code{nil}, that means no default has been specified; then if the user
+enters null input, the return value is @code{nil}.
@example
(read-command "Command name? ")
symbol.
The argument @var{default} specifies what to return if the user enters
-null input. It can be a symbol or a string, but the value returned by
-@code{read-variable} is always a symbol. If @var{default} is
-@code{nil}, that means no default has been specified; then if the user
-enters null input, the return value is @code{nil}.
+null input. It can be a symbol or a string; if it is a string,
+@code{read-variable} interns it before returning it. If @var{default}
+is @code{nil}, that means no default has been specified; then if the
+user enters null input, the return value is @code{nil}.
@example
@group
@end example
@end defun
-@tindex read-coding-system
-@defun read-coding-system prompt default
-This function reads a coding system using the minibuffer, prompting with
-string @var{prompt}, and returns the coding system name as a symbol. If
-the user tries to enter null input, it asks the user to try again.
-@xref{Coding Systems}.
-@end defun
-
-@tindex read-non-nil-coding-system
-@defun read-non-nil-coding-system prompt
-This function reads a coding system using the minibuffer, prompting with
-string @var{prompt},and returns the coding system name as a symbol. If
-the user enters null input, it returns @var{default-coding-system}.
-which should be a symbol or a string. @xref{Coding Systems}.
-@end defun
+ See also the functions @code{read-coding-system} and
+@code{read-non-nil-coding-system}, in @ref{Lisp and Coding Systems}.
@node Reading File Names
@subsection Reading File Names
the buffer (after with @var{directory}, if that is inserted). In this
case, point goes at the beginning of @var{initial}. The default for
@var{initial} is @code{nil}---don't insert any file name. To see what
-@var{initial} does, try the command @kbd{C-x C-v}.
+@var{initial} does, try the command @kbd{C-x C-v}. @strong{Note:} we
+recommend using @var{default} rather than @var{initial} in most cases.
Here is an example:
matches no possibility.
If the string is an exact match for one possibility, but also matches
-other longer possibilities, the function shuold return the string, not
+other longer possibilities, the function should return the string, not
@code{t}.
@item
@defopt enable-recursive-minibuffers
If this variable is non-@code{nil}, you can invoke commands (such as
-@code{find-file}) that use minibuffers even while in the minibuffer
-window. Such invocation produces a recursive editing level for a new
+@code{find-file}) that use minibuffers even while the minibuffer window
+is active. Such invocation produces a recursive editing level for a new
minibuffer. The outer-level minibuffer is invisible while you are
editing the inner one.
-This variable only affects invoking the minibuffer while the
-minibuffer window is selected. If you switch windows while in the
-minibuffer, you can always invoke minibuffer commands while some other
-window is selected.
+If this variable is @code{nil}, you cannot invoke minibuffer
+commands when the minibuffer window is active, not even if you switch to
+another window to do it.
@end defopt
@c Emacs 19 feature
Emacs command behaves in its default manner, and each option is in its
default state. All other major modes redefine various keys and options.
For example, Lisp Interaction mode provides special key bindings for
-@key{LFD} (@code{eval-print-last-sexp}), @key{TAB}
+@kbd{C-j} (@code{eval-print-last-sexp}), @key{TAB}
(@code{lisp-indent-line}), and other keys.
When you need to write several editing commands to help you perform a
Text mode except that it provides three additional commands. Its
definition is distinct from that of Text mode, but was derived from it.
- Rmail Edit mode is an example of a case where one piece of text is put
-temporarily into a different major mode so it can be edited in a
-different way (with ordinary Emacs commands rather than Rmail). In such
-cases, the temporary major mode usually has a command to switch back to
-the buffer's usual mode (Rmail mode, in this case). You might be
-tempted to present the temporary redefinitions inside a recursive edit
-and restore the usual ones when the user exits; but this is a bad idea
-because it constrains the user's options when it is done in more than
-one buffer: recursive edits must be exited most-recently-entered first.
-Using alternative major modes avoids this limitation. @xref{Recursive
+ Rmail Edit mode offers an example of changing the major mode
+temporarily for a buffer, so it can be edited in a different way (with
+ordinary Emacs commands rather than Rmail). In such cases, the
+temporary major mode usually has a command to switch back to the
+buffer's usual mode (Rmail mode, in this case). You might be tempted to
+present the temporary redefinitions inside a recursive edit and restore
+the usual ones when the user exits; but this is a bad idea because it
+constrains the user's options when it is done in more than one buffer:
+recursive edits must be exited most-recently-entered first. Using an
+alternative major mode avoids this limitation. @xref{Recursive
Editing}.
The standard GNU Emacs Lisp library directory contains the code for
@item
Define a command whose name ends in @samp{-mode}, with no arguments,
that switches to the new mode in the current buffer. This command
-should set up the keymap, syntax table, and local variables in an
-existing buffer without changing the buffer's text.
+should set up the keymap, syntax table, and buffer-local variables in an
+existing buffer, without changing the buffer's contents.
@item
Write a documentation string for this command that describes the
@item
The major mode command should start by calling
-@code{kill-all-local-variables}. This is what gets rid of the local
-variables of the major mode previously in effect.
+@code{kill-all-local-variables}. This is what gets rid of the
+buffer-local variables of the major mode previously in effect.
@item
The major mode command should set the variable @code{major-mode} to the
@item
The major mode command should set the variable @code{mode-name} to the
-``pretty'' name of the mode, as a string. This appears in the mode
-line.
+``pretty'' name of the mode, as a string. This string appears in the
+mode line.
@item
@cindex functions in modes
@item
@cindex keymaps in modes
The major mode should usually have its own keymap, which is used as the
-local keymap in all buffers in that mode. The major mode function
-should call @code{use-local-map} to install this local map.
-@xref{Active Keymaps}, for more information.
+local keymap in all buffers in that mode. The major mode command should
+call @code{use-local-map} to install this local map. @xref{Active
+Keymaps}, for more information.
-This keymap should be kept in a global variable named
+This keymap should be stored permanently in a global variable named
@code{@var{modename}-mode-map}. Normally the library that defines the
mode sets this variable.
@item
The key sequences bound in a major mode keymap should usually start with
-@kbd{C-c}, followed by a control-character, a digit, or @kbd{@{},
+@kbd{C-c}, followed by a control character, a digit, or @kbd{@{},
@kbd{@}}, @kbd{<}, @kbd{>}, @kbd{:} or @kbd{;}. The other punctuation
characters are reserved for minor modes, and ordinary letters are
reserved for users.
Tables}.
@item
-@vindex font-lock-defaults
The mode should specify how to do highlighting for Font Lock mode, by
setting up a buffer-local value for the variable
-@code{font-lock-defaults}.
+@code{font-lock-defaults} (@pxref{Font Lock Mode}).
@item
-@vindex imenu-generic-expression
-@vindex imenu-create-index-function
The mode should specify how Imenu should find the definitions or
sections of a buffer, by setting up a buffer-local value for the
variable @code{imenu-generic-expression} or
-@code{imenu-create-index-function}.
+@code{imenu-create-index-function} (@pxref{Imenu}).
@item
-Use @code{defvar} to set mode-related variables, so that they are not
-reinitialized if they already have a value. (Such reinitialization
-could discard customizations made by the user.)
+Use @code{defvar} or @code{defcustom} to set mode-related variables, so
+that they are not reinitialized if they already have a value. (Such
+reinitialization could discard customizations made by the user.)
@item
@cindex buffer-local variables in modes
would affect buffers that do not use this mode. It is undesirable for a
mode to have such global effects. @xref{Buffer-Local Variables}.
-It's ok to use @code{make-variable-buffer-local}, if you wish, for a
+It's OK to use @code{make-variable-buffer-local}, if you wish, for a
variable used only within a single Lisp package.
@item
@item
If something special should be done if the user switches a buffer from
this mode to any other major mode, this mode can set up a buffer-local
-value for @code{change-major-mode-hook} (see below).
+value for @code{change-major-mode-hook} (@pxref{Creating Buffer-Local}).
@item
If this mode is appropriate only for specially-prepared text, then the
Even if you never load the file more than once, someone else will.
@end itemize
-@defvar change-major-mode-hook
-The function @code{kill-all-local-variables} runs this normal hook
-before it does anything else. This gives major modes a way to arrange
-for something special to be done if the user switches to a different
-major mode. For best results, make this variable buffer-local, so that
-it will disappear after doing its job and will not interfere with the
-subsequent major mode. @xref{Hooks}.
-@end defvar
-
@node Example Major Modes
@subsection Major Mode Examples
@smallexample
@group
(defun text-mode ()
- "Major mode for editing text intended for humans to read.
+ "Major mode for editing text intended for humans to read@enddots{}
Special commands: \\@{text-mode-map@}
@end group
@group
Turning on text-mode runs the hook `text-mode-hook'."
(interactive)
(kill-all-local-variables)
+ (use-local-map text-mode-map)
@end group
@group
- (use-local-map text-mode-map) ; @r{This provides the local keymap.}
- (setq mode-name "Text") ; @r{This name goes into the mode line.}
- (setq major-mode 'text-mode) ; @r{This is how @code{describe-mode}}
- ; @r{finds the doc string to print.}
(setq local-abbrev-table text-mode-abbrev-table)
(set-syntax-table text-mode-syntax-table)
+@end group
+@group
+ (make-local-variable 'paragraph-start)
+ (setq paragraph-start (concat "[ \t]*$\\|" page-delimiter))
+ (make-local-variable 'paragraph-separate)
+ (setq paragraph-separate paragraph-start)
+@end group
+@group
+ (setq mode-name "Text")
+ (setq major-mode 'text-mode)
(run-hooks 'text-mode-hook)) ; @r{Finally, this permits the user to}
; @r{customize the mode with a hook.}
@end group
@smallexample
@group
(defun lisp-mode-variables (lisp-syntax)
- ;; @r{The @code{lisp-syntax} argument is @code{nil} in Emacs Lisp mode,}
- ;; @r{and @code{t} in the other two Lisp modes.}
(cond (lisp-syntax
- (if (not lisp-mode-syntax-table)
- ;; @r{The Emacs Lisp mode syntax table always exists, but}
- ;; @r{the Lisp Mode syntax table is created the first time a}
- ;; @r{mode that needs it is called. This is to save space.}
-@end group
-@group
- (progn (setq lisp-mode-syntax-table
- (copy-syntax-table emacs-lisp-mode-syntax-table))
- ;; @r{Change some entries for Lisp mode.}
- (modify-syntax-entry ?\| "\" "
- lisp-mode-syntax-table)
- (modify-syntax-entry ?\[ "_ "
- lisp-mode-syntax-table)
- (modify-syntax-entry ?\] "_ "
- lisp-mode-syntax-table)))
-@end group
-@group
- (set-syntax-table lisp-mode-syntax-table)))
+ (set-syntax-table lisp-mode-syntax-table)))
(setq local-abbrev-table lisp-mode-abbrev-table)
@dots{})
@end group
@smallexample
@group
(make-local-variable 'paragraph-start)
- ;; @r{Having @samp{^} is not clean, but @code{page-delimiter}}
- ;; @r{has them too, and removing those is a pain.}
- (setq paragraph-start (concat "^$\\|" page-delimiter))
+ (setq paragraph-start (concat page-delimiter "\\|$" ))
+ (make-local-variable 'paragraph-separate)
+ (setq paragraph-separate paragraph-start)
@dots{}
@end group
@group
Each of the different Lisp modes has a slightly different keymap. For
example, Lisp mode binds @kbd{C-c C-z} to @code{run-lisp}, but the other
Lisp modes do not. However, all Lisp modes have some commands in
-common. The following function adds these common commands to a given
-keymap.
+common. The following code sets up the common commands:
@smallexample
@group
-(defun lisp-mode-commands (map)
- (define-key map "\e\C-q" 'indent-sexp)
- (define-key map "\177" 'backward-delete-char-untabify)
- (define-key map "\t" 'lisp-indent-line))
+(defvar shared-lisp-mode-map ()
+ "Keymap for commands shared by all sorts of Lisp modes.")
+
+(if shared-lisp-mode-map
+ ()
+ (setq shared-lisp-mode-map (make-sparse-keymap))
+ (define-key shared-lisp-mode-map "\e\C-q" 'indent-sexp)
+ (define-key shared-lisp-mode-map "\177"
+ 'backward-delete-char-untabify))
@end group
@end smallexample
- Here is an example of using @code{lisp-mode-commands} to initialize a
-keymap, as part of the code for Emacs Lisp mode. First we declare a
-variable with @code{defvar} to hold the mode-specific keymap. When this
-@code{defvar} executes, it sets the variable to @code{nil} if it was
-void. Then we set up the keymap if the variable is @code{nil}.
-
- This code avoids changing the keymap or the variable if it is already
-set up. This lets the user customize the keymap.
+@noindent
+And here is the code to set up the keymap for Lisp mode:
@smallexample
@group
-(defvar emacs-lisp-mode-map () "")
-(if emacs-lisp-mode-map
+(defvar lisp-mode-map ()
+ "Keymap for ordinary Lisp mode@enddots{}")
+
+(if lisp-mode-map
()
- (setq emacs-lisp-mode-map (make-sparse-keymap))
- (define-key emacs-lisp-mode-map "\e\C-x" 'eval-defun)
- (lisp-mode-commands emacs-lisp-mode-map))
+ (setq lisp-mode-map (make-sparse-keymap))
+ (set-keymap-parent lisp-mode-map shared-lisp-mode-map)
+ (define-key lisp-mode-map "\e\C-x" 'lisp-eval-defun)
+ (define-key lisp-mode-map "\C-c\C-z" 'run-lisp))
@end group
@end smallexample
@smallexample
@group
-(defun emacs-lisp-mode ()
- "Major mode for editing Lisp code to run in Emacs.
+(defun lisp-mode ()
+ "Major mode for editing Lisp code for Lisps other than GNU Emacs Lisp.
Commands:
Delete converts tabs to spaces as it moves back.
Blank lines separate paragraphs. Semicolons start comments.
-\\@{emacs-lisp-mode-map@}
+\\@{lisp-mode-map@}
+Note that `run-lisp' may be used either to start an inferior Lisp job
+or to switch back to an existing one.
@end group
+
@group
-Entry to this mode runs the hook `emacs-lisp-mode-hook'."
+Entry to this mode calls the value of `lisp-mode-hook'
+if that value is non-nil."
(interactive)
(kill-all-local-variables)
- (use-local-map emacs-lisp-mode-map) ; @r{This provides the local keymap.}
- (set-syntax-table emacs-lisp-mode-syntax-table)
@end group
@group
- (setq major-mode 'emacs-lisp-mode) ; @r{This is how @code{describe-mode}}
+ (use-local-map lisp-mode-map) ; @r{Select the mode's keymap.}
+ (setq major-mode 'lisp-mode) ; @r{This is how @code{describe-mode}}
; @r{finds out what to describe.}
- (setq mode-name "Emacs-Lisp") ; @r{This goes into the mode line.}
- (lisp-mode-variables nil) ; @r{This defines various variables.}
- (run-hooks 'emacs-lisp-mode-hook)) ; @r{This permits the user to use a}
+ (setq mode-name "Lisp") ; @r{This goes into the mode line.}
+ (lisp-mode-variables t) ; @r{This defines various variables.}
+@end group
+@group
+ (setq imenu-case-fold-search t)
+ (set-syntax-table lisp-mode-syntax-table)
+ (run-hooks 'lisp-mode-hook)) ; @r{This permits the user to use a}
; @r{hook to customize the mode.}
@end group
@end smallexample
Based on information in the file name or in the file itself, Emacs
automatically selects a major mode for the new buffer when a file is
-visited.
+visited. It also processes local variables specified in the file text.
@deffn Command fundamental-mode
Fundamental mode is a major mode that is not specialized for anything
@end deffn
@deffn Command normal-mode &optional find-file
-This function establishes the proper major mode and local variable
+This function establishes the proper major mode and buffer-local variable
bindings for the current buffer. First it calls @code{set-auto-mode},
then it runs @code{hack-local-variables} to parse, and bind or
-evaluate as appropriate, any local variables.
+evaluate as appropriate, the file's local variables.
-If the @var{find-file} argument to @code{normal-mode} is
-non-@code{nil}, @code{normal-mode} assumes that the @code{find-file}
-function is calling it. In this case, it may process a local variables
-list at the end of the file and in the @samp{-*-} line. The variable
-@code{enable-local-variables} controls whether to do so.
+If the @var{find-file} argument to @code{normal-mode} is non-@code{nil},
+@code{normal-mode} assumes that the @code{find-file} function is calling
+it. In this case, it may process a local variables list at the end of
+the file and in the @samp{-*-} line. The variable
+@code{enable-local-variables} controls whether to do so. @xref{File
+variables, , Local Variables in Files, emacs, The GNU Emacs Manual}, for
+the syntax of the local variables section of a file.
If you run @code{normal-mode} interactively, the argument
@var{find-file} is normally @code{nil}. In this case,
@code{normal-mode} unconditionally processes any local variables list.
-@xref{File variables, , Local Variables in Files, emacs, The GNU Emacs
-Manual}, for the syntax of the local variables section of a file.
@cindex file mode specification error
@code{normal-mode} uses @code{condition-case} around the call to the
@defvar ignored-local-variables
This variable holds a list of variables that should not be
-set by a local variables list. Any value specified
+set by a file's local variables list. Any value specified
for one of these variables is ignored.
@end defvar
current buffer. It may base its decision on the value of the @w{@samp{-*-}}
line, on the visited file name (using @code{auto-mode-alist}), on the
@w{@samp{#!}} line (using @code{interpreter-mode-alist}), or on the
-value of a local variable. However, this function does not look for
+file's local variables list. However, this function does not look for
the @samp{mode:} local variable near the end of a file; the
@code{hack-local-variables} function does that. @xref{Choosing Modes, ,
How Major Modes are Chosen, emacs, The GNU Emacs Manual}.
@end defun
@defopt default-major-mode
- This variable holds the default major mode for new buffers. The
+This variable holds the default major mode for new buffers. The
standard value is @code{fundamental-mode}.
- If the value of @code{default-major-mode} is @code{nil}, Emacs uses
+If the value of @code{default-major-mode} is @code{nil}, Emacs uses
the (previously) current buffer's major mode for the major mode of a new
buffer. However, if that major mode symbol has a @code{mode-class}
property with value @code{special}, then it is not used for new buffers;
@smallexample
@group
-(("^/tmp/fol/" . text-mode)
+(("\\`/tmp/fol/" . text-mode)
("\\.texinfo\\'" . texinfo-mode)
("\\.texi\\'" . texinfo-mode)
@end group
If an element of @code{auto-mode-alist} has the form @code{(@var{regexp}
@var{function} t)}, then after calling @var{function}, Emacs searches
@code{auto-mode-alist} again for a match against the portion of the file
-name that did not match before.
-
-This match-again feature is useful for uncompression packages: an entry
-of the form @code{("\\.gz\\'" @var{function} t)} can uncompress the file
-and then put the uncompressed file in the proper mode according to the
-name sans @samp{.gz}.
+name that did not match before. This feature is useful for
+uncompression packages: an entry of the form @code{("\\.gz\\'"
+@var{function} t)} can uncompress the file and then put the uncompressed
+file in the proper mode according to the name sans @samp{.gz}.
Here is an example of how to prepend several pattern pairs to
@code{auto-mode-alist}. (You might use this sort of expression in your
@end defvar
@defun hack-local-variables &optional force
- This function parses, and binds or evaluates as appropriate, any local
-variables for the current buffer.
+This function parses, and binds or evaluates as appropriate, any local
+variables specified by the contents of the current buffer.
- The handling of @code{enable-local-variables} documented for
+The handling of @code{enable-local-variables} documented for
@code{normal-mode} actually takes place here. The argument @var{force}
usually comes from the argument @var{find-file} given to
@code{normal-mode}.
A @dfn{minor mode} provides features that users may enable or disable
independently of the choice of major mode. Minor modes can be enabled
individually or in combination. Minor modes would be better named
-``Generally available, optional feature modes'' except that such a name is
-unwieldy.
+``generally available, optional feature modes,'' except that such a name
+would be unwieldy.
A minor mode is not usually a modification of single major mode. For
-example, Auto Fill mode may be used in any major mode that permits text
+example, Auto Fill mode works with any major mode that permits text
insertion. To be general, a minor mode must be effectively independent
of the things major modes do.
@itemize @bullet
@item
@cindex mode variable
-Make a variable whose name ends in @samp{-mode} to represent the minor
-mode. Its value should enable or disable the mode (@code{nil} to
-disable; anything else to enable.) We call this the @dfn{mode
-variable}.
+Make a variable whose name ends in @samp{-mode} to control the minor
+mode. We call this the @dfn{mode variable}. The minor mode command
+should set this variable (@code{nil} to disable; anything else to
+enable.)
+
+If it is possible, implement the mode so that setting the variable
+automatically enables or disables the mode. Then the minor mode command
+does not need to do anything except the variable.
This variable is used in conjunction with the @code{minor-mode-alist} to
display the minor mode name in the mode line. It can also enable
@item
Add an element to @code{minor-mode-alist} for each minor mode
-(@pxref{Mode Line Variables}). This element should be a list of the
-following form:
+(@pxref{Mode Line Variables}), if you want to indicate the minor mode in
+the mode line. This element should be a list of the following form:
@smallexample
(@var{mode-variable} @var{string})
Here is an example of using @code{easy-mmode-define-minor-mode}:
@smallexample
-(easy-mmode-define-minor-mode
- hungry-mode
- "Toggle Hungry mode.
+(easy-mmode-define-minor-mode hungry-mode
+ "Toggle Hungry mode.
With no argument, this command toggles the mode.
Non-null prefix argument turns on the mode.
Null prefix argument turns off the mode.
mode is enabled. It initializes the keymap with key bindings for
@kbd{C-@key{DEL}} and @kbd{C-M-@key{DEL}}.
- The command @code{hungry-mode} also runs three hooks:
-@code{hungry-mode-on-hook} when enabling Hungry mode,
-@code{hungry-mode-off-hook} when disabling the mode, and
-@code{hungry-mode-hook} in both of those cases.
-
@node Mode Line Format
@section Mode Line Format
@cindex mode line
@code{mode-line-format} is a buffer-local variable that holds a
template used to display the mode line of the current buffer. All
windows for the same buffer use the same @code{mode-line-format} and
-their mode lines appear the same (except for scrolling percentages and
-line numbers).
+their mode lines appear the same (except for scrolling percentages, and
+line and column numbers).
The mode line of a window is normally updated whenever a different
buffer is shown in the window, or when the buffer's modified-status
@cindex Shell mode @code{mode-line-format}
Here is an example of a @code{mode-line-format} that might be
-useful for @code{shell-mode}, since it contains the hostname and default
+useful for @code{shell-mode}, since it contains the host name and default
directory.
@example
@group
(setq mode-line-format
- (list ""
+ (list "-"
+ 'mode-line-mule-info
'mode-line-modified
+ 'mode-line-frame-identification
"%b--"
@end group
@group
'mode-line-process
'minor-mode-alist
"%n"
- ")%]----"
+ ")%]--"
@group
+ '(which-func-mode ("" which-func-format "--"))
'(line-number-mode "L%l--")
+ '(column-number-mode "C%c--")
'(-3 . "%p")
"-%-"))
@end group
other variables could have the same effects on the mode line if
@code{mode-line-format} were changed to use them.
+@tindex mode-line-mule-info
+@defvar mode-line-mule-info
+This variable holds the value of the mode-line construct that displays
+information about the language environment, buffer coding system, and
+current input method. @xref{International,,, emacs, The GNU Emacs
+Manual}.
+@end defvar
+
@defvar mode-line-modified
This variable holds the value of the mode-line construct that displays
whether the current buffer is modified.
-The default value of @code{mode-line-modified} is @code{("--%1*%1+-")}.
-This means that the mode line displays @samp{--**-} if the buffer is
-modified, @samp{-----} if the buffer is not modified, @samp{--%%-} if
-the buffer is read only, and @samp{--%*--} if the buffer is read only
-and modified.
+The default value of @code{mode-line-modified} is @code{("%1*%1+")}.
+This means that the mode line displays @samp{**} if the buffer is
+modified, @samp{--} if the buffer is not modified, @samp{%%} if the
+buffer is read only, and @samp{%*} if the buffer is read only and
+modified.
Changing this variable does not force an update of the mode line.
@end defvar
+@tindex mode-line-frame-identification
+@defvar mode-line-frame-identification
+This variable identifies the current frame. The default value is
+@code{" "} if you are using a window system which can show multiple
+frames, or @code{"-%F "} on an ordinary terminal which shows only one
+frame at a time.
+@end defvar
+
@defvar mode-line-buffer-identification
This variable identifies the buffer being displayed in the window. Its
-default value is @code{("%F: %17b")}, which means that it usually
+default value is @code{("%12b")}, which means that it usually
displays @samp{Emacs:} followed by seventeen characters of the buffer
name. (In a terminal frame, it displays the frame name instead of
@samp{Emacs}; this has the effect of showing the frame number.) You may
@end defvar
@defvar vc-mode
-The variable @code{vc-mode}, local in each buffer, records whether the
-buffer's visited file is maintained with version control, and, if so,
-which kind. Its value is @code{nil} for no version control, or a string
-that appears in the mode line.
+The variable @code{vc-mode}, buffer-local in each buffer, records
+whether the buffer's visited file is maintained with version control,
+and, if so, which kind. Its value is @code{nil} for no version control,
+or a string that appears in the mode line.
@end defvar
@node %-Constructs
function. @xref{Buffer File Name}.
@item %F
-The name of the selected frame.
+The title (only on a window system) or the name of the selected frame.
+@xref{Window Frame Parameters}.
@item %c
The current column number of point.
@section Imenu
@cindex Imenu
- @dfn{Imenu} is a feature that constructs a buffer index for a buffer.
-The buffer index contains the names and positions of the definitions or
-portions of in the buffer, so the user can pick one of themand move to
-it. This section explains how to customize Imenu for a major mode. The
-usual and simplest way is to set the variable
-@code{imenu-generic-expression}.
+ @dfn{Imenu} is a feature that lets users select a definition or
+section in the buffer, from a menu which lists all of them, to go
+directly to that location in the buffer. Imenu works by constructing a
+buffer index which lists the names and positions of the definitions or
+portions of in the buffer, so the user can pick one of them to move to.
+This section explains how to customize Imenu for a major mode.
+
+ The usual and simplest way is to set the variable
+@code{imenu-generic-expression}:
@defvar imenu-generic-expression
This variable, if non-@code{nil}, specifies regular expressions for
The second item in the list, @var{regexp}, is a regular expression
(@pxref{Regular Expressions}); wherever it matches, that is a definition
-to be mentioned in the buffer index. The third item, @var{subexp},
-indicates which subexpression in @var{regexp} contains the name for the
-definition.
+to mention in the buffer index. The third item, @var{subexp}, indicates
+which subexpression in @var{regexp} matches the definition's name.
An element can also look like this:
@end group
@end example
-This variable is local in all buffers, if it is set.
+Setting this variable makes it buffer-local in the current buffer.
@end defvar
@defvar imenu-case-fold-search
is case-sensitive: @code{t}, the default, means matching should ignore
case.
-This variable is local in all buffers, if it is set.
+Setting this variable makes it buffer-local in the current buffer.
@end defvar
Another way to customize Imenu for a major mode is to set the
variables @code{imenu-prev-index-position-function} and
-@code{imenu-extract-index-name-function}.
+@code{imenu-extract-index-name-function}:
@defvar imenu-prev-index-position-function
If this variable is non-@code{nil}, its value should be a function for
backwards in the file.
The function should leave point at the place to be connected to the
-index item, and it should return @code{nil} when it doesn't find another
-item.
+index item; it should return @code{nil} if it doesn't find another item.
-This variable is local in all buffers, if it is set.
+Setting this variable makes it buffer-local in the current buffer.
@end defvar
@defvar imenu-extract-index-name-function
If this variable is non-@code{nil}, its value should be a function to
-return the name for a definition, assuming point is at that definition.
+return the name for a definition, assuming point is in that definition
+as the @code{imenu-prev-index-position-function} function would leave
+it.
-This variable is local in all buffers, if it is set.
+Setting this variable makes it buffer-local in the current buffer.
@end defvar
+ The last way to customize Imenu for a major mode is to set the
+variables @code{imenu-create-index-function}:
+
@defvar imenu-create-index-function
This variable specifies the function to use for creating a buffer index.
The function should take no arguments, and return an index for the
specify a different function, then @code{imenu-generic-expression} is
not used.
-The variable @code{imenu-create-index-function} is local in all buffers,
-if it is set.
+Setting this variable makes it buffer-local in the current buffer.
@end defvar
@defvar imenu-index-alist
This variable holds the index alist for the current buffer.
-It is local in each buffer, once it is set.
+Setting it makes it buffer-local in the current buffer.
Simple elements in the alist look like @code{(@var{index-name}
. @var{index-position})}. Selecting a simple element has the effect of
@dfn{Font Lock mode} is a feature that automatically attaches
@code{face} properties to certain parts of the buffer based on their
syntactic role. How it parses the buffer depends on the major mode;
-most major modes define a set of syntactic criteria for which faces to
-use, in which contexts. This section explains how to customize Font
-Lock for a particular language---in other words, for a particular major
-mode.
+most major modes define syntactic criteria for which faces to use, in
+which contexts. This section explains how to customize Font Lock for a
+particular language---in other words, for a particular major mode.
Font Lock mode finds text to highlight in two ways: through syntactic
parsing based on the syntax table, and through searching (usually for
regular expressions). Syntactic fontification happens first; it finds
comments and string constants, and highlights them using
@code{font-lock-comment-face} and @code{font-lock-string-face}
-(@pxref{Faces for Font Lock}: Search-based fontification follows.
+(@pxref{Faces for Font Lock}); search-based fontification follows.
@menu
* Font Lock Basics::
* Other Font Lock Variables::
* Levels of Font Lock::
* Faces for Font Lock::
+* Syntactic Font Lock::
@end menu
@node Font Lock Basics
There are several variables that control how Font Lock mode highlights
text. But major modes should not set any of these variables directly.
-Instead, it should set @code{font-lock-defaults} as a local variable.
-The value assigned to this variable is used, if and when Font Lock mode
-is enabled, to set all the other variables.
+Instead, it should set @code{font-lock-defaults} as a buffer-local
+variable. The value assigned to this variable is used, if and when Font
+Lock mode is enabled, to set all the other variables.
@defvar font-lock-defaults
This variable is set by major modes, as a buffer-local variable, to
The second element, @var{keywords-only}, specifies the value of the
variable @code{font-lock-keywords-only}. If this is is non-@code{nil},
-syntactic fontification (strings and comments) is not performed.
+syntactic fontification (of strings and comments) is not performed.
The third element, @var{case-fold}, specifies the value of
@code{font-lock-case-fold-search}. If it is non-@code{nil}, Font Lock
-mode ignores case when obeying @code{font-lock-keywords}.
+mode ignores case when searching as directed by
+@code{font-lock-keywords}.
If the fourth element, @var{syntax-alist}, is non-@code{nil}, it should be
a list of cons cells of the form @code{(@var{char-or-string}
table is stored in @code{font-lock-syntax-table}.
The fifth element, @var{syntax-begin}, specifies the value of
-@code{font-lock-beginning-of-syntax-function}. See below for an
-explanation of what this value means.
+@code{font-lock-beginning-of-syntax-function} (see below).
Any further elements @var{other-vars} are have form
@code{(@var{variable} . @var{value})}. This kind of element means to
@defvar font-lock-keywords
This variable's value is a list of the keywords to highlight. Be
-careful when composing regexps for this list; a poorly written pattern
-can dramatically slow things down!
+careful when composing regular expressions for this list; a poorly
+written pattern can dramatically slow things down!
@end defvar
Each element of @code{font-lock-keywords} specifies how to find
-certain cases of text, and how to highlight those cases. An element
-should have one of these forms:
+certain cases of text, and how to highlight those cases. Font Lock mode
+processes the elements of @code{font-lock-keywords} one by one, and for
+each element, it finds and handles all matches. Ordinarily, once
+part of the text has been fontified already, this cannot be overridden
+by a subsequent match in the same text; but you can specify different
+behavior using the @var{override} element of a @var{highlighter}.
+
+ Each element of @code{font-lock-keywords} should have one of these
+forms:
@table @code
@item @var{regexp}
"\\<foo\\>"
@end example
-The function @code{regexp-opt} (@pxref{Syntax of Regexps}) is often
-useful for calculating complex regular expressions to match a number of
-different keywords.
+The function @code{regexp-opt} (@pxref{Syntax of Regexps}) is useful for
+calculating optimal regular expressions to match a number of different
+keywords.
@item @var{function}
Find text by calling @var{function}, and highlight the matches
In this kind of element, @var{matcher} stands for either a regular
expression or a function, as described above. The @sc{cdr},
@var{match}, specifies which subexpression of @var{matcher} should be
-highlighted (instead of the entire text that matched @var{matcher}).
+highlighted (instead of the entire text that @var{matcher} matched).
@example
;; @r{Highlight the @samp{bar} in each occurrences of @samp{fubar},}
("fu\\(bar\\)" . 1)
@end example
-If you use @code{regexp-opt} to produce a regular expression for
+If you use @code{regexp-opt} to produce the regular expression
@var{matcher}, then you can use @code{regexp-opt-depth} (@pxref{Syntax
of Regexps}) to calculate the value for @var{match}.
@end example
The @sc{car}, @var{subexp}, is an integer specifying which subexpression
-of the match to fontify (0 means the entire matching text).
-@var{facename}, specifies the face, as described above.
+of the match to fontify (0 means the entire matching text). The second
+subelement, @var{facename}, specifies the face, as described above.
The last two values in @var{highlighter}, @var{override} and
@var{laxmatch}, are flags. If @var{override} is @code{t}, this element
@end ignore
@item (eval . @var{form})
-Here @var{form} is an expression. to be evaluated the first time
+Here @var{form} is an expression to be evaluated the first time
this value of @code{font-lock-keywords} is used in a buffer.
-Its value should be another element of one of these forms.
+Its value should have one of the forms described in this table.
@end table
@strong{Warning:} Do not design an element of @code{font-lock-keywords}
updating when you edit the buffer does not, since it considers text one
line at a time.
-@defvar font-lock-syntactic-keywords
-Font Lock mode can be used to update @code{syntax-table} properties
-automatically. This is useful in languages for which a single
-syntax table by itself is not sufficient.
-
-This variable enables and controls the feature. Its value should
-be a list of elements of this form:
-
-@example
-(@var{matcher} @var{subexp} @var{syntax} @var{override} @var{laxmatch})
-@end example
-
-The parts of this element have the same meanings as in the corresponding
-sort of element of @code{font-lock-keywords},
-
-@example
-(@var{matcher} @var{subexp} @var{facename} @var{override} @var{laxmatch})
-@end example
-
-However, instead of specifying the value @var{facename} to use for the
-@code{face} property, it specifies the value @var{syntax} to use for the
-@code{syntax-table} property. Here, @var{syntax} can be a variable
-whose value is a syntax table, a syntax entry of the form
-@code{(@var{syntax-code} . @var{matching-char})}, or an expression whose
-value is one of those two types.
-@end defvar
-
@node Other Font Lock Variables
@subsection Other Font Lock Variables
@defvar font-lock-keywords-only
Non-@code{nil} means Font Lock should not fontify comments or strings
-syntactictally; it should only fontify based on @code{font-lock-keywords}.
+syntactically; it should only fontify based on
+@code{font-lock-keywords}.
@end defvar
@ignore
@end ignore
@defvar font-lock-keywords-case-fold-search
-Non-@code{nil} means that regular expression matching for
-patterns in @code{font-lock-keywords} is case-insensitive.
+Non-@code{nil} means that regular expression matching for the sake of
+@code{font-lock-keywords} should be case-insensitive.
@end defvar
-@defvar font-lock-beginning-of-syntax-function
-If this variable is non-@code{nil}, it should be a function to use to
-move back outside of a syntactic block.
+@defvar font-lock-syntax-table
+This variable specifies the syntax table to use for fontification of
+comments and strings.
+@end defvar
-@c Simon, WHEN is this variable used?
-@c In what situation does Font Lock mode look for the
-@c beginning of a syntactic block?
+@defvar font-lock-beginning-of-syntax-function
+If this variable is non-@code{nil}, it should be a function to move
+point back to a position that is syntactically at ``top level'' and
+outside of strings or comments. Font Lock uses this when necessary
+to get the right results for syntactic fontification.
This function is called with no arguments. It should leave point at the
beginning of any enclosing syntactic block. Typical values are
mode-dependent function is known to move outside a syntactic block).
If the value is @code{nil}, the beginning of the buffer is used as a
-position outside of a syntactic block, in the worst case.
-@end defvar
-
-@defvar font-lock-syntax-table
-This variable specifies the syntax table to use for fontification of
-comments and strings.
+position outside of a syntactic block. This cannot be wrong, but it can
+be slow.
@end defvar
@defvar font-lock-mark-block-function
-If this variable is non-@code{nil}, it should be a function with no args
-used to mark an enclosing range of text for refontification when the
-text in the buffer changes. A good choice of this function chooses a
-range of text large enough to give proper results, but not too large so
-that refontification becomes slow.
-
-Typical values are @code{mark-defun} for programming modes or
-@code{mark-paragraph} for textual modes (i.e., the mode-dependent
-function is known to put point and mark around a text block relevant to
-that mode).
-
-@c Simon, WHEN is this variable used?
-@c In what situation does Font Lock mode look for the
-@c beginning of a syntactic block?
-
+If this variable is non-@code{nil}, it should be a function that is
+called with no arguments, to choose an enclosing range of text for
+refontification for the command @kbd{M-g M-g}
+(@code{font-lock-fontify-block}).
+
+The function should report its choice by placing the region around it.
+A good choice is a range of text large enough to give proper results,
+but not too large so that refontification becomes slow. Typical values
+are @code{mark-defun} for programming modes or @code{mark-paragraph} for
+textual modes.
@end defvar
@node Levels of Font Lock
chosen level's symbol value is used to initialize
@code{font-lock-keywords}.
+ Here are the conventions for how to define the levels of
+fontification:
+
@itemize @bullet
@item
Level 1: highlight function declarations, file directives (such as include or
the most important and top-level components are fontified.
@item
-Level 2: in addition to level 1, highlight all language keywords (with
-keyword-face) including type names (using type-face), constant values
-(with reference-face, e.g., "true" and "false" or case/switch
-constants). The idea is that all reserved words should be fontified
-appropriately.
+Level 2: in addition to level 1, highlight all language keywords,
+including type names that act like keywords, as well as named constant
+values. The idea is that all keywords (either syntactic or semantic)
+should be fontified appropriately.
@item
-Level 3: in addition to level 2, highlight all symbols that are defined
-in function and variable declarations, and all builtin functions,
-wherever they appear. The idea is that all declared objects should be
-fontified.
+Level 3: in addition to level 2, highlight the symbols being defined in
+function and variable declarations, and all builtin function names,
+wherever they appear.
@end itemize
@node Faces for Font Lock
directives in C.
@end table
+@node Syntactic Font Lock
+@subsection Syntactic Font Lock
+
+ Font Lock mode can be used to update @code{syntax-table} properties
+automatically. This is useful in languages for which a single syntax
+table by itself is not sufficient.
+
+@defvar font-lock-syntactic-keywords
+This variable enables and controls syntactic Font Lock. Its value
+should be a list of elements of this form:
+
+@example
+(@var{matcher} @var{subexp} @var{syntax} @var{override} @var{laxmatch})
+@end example
+
+The parts of this element have the same meanings as in the corresponding
+sort of element of @code{font-lock-keywords},
+
+@example
+(@var{matcher} @var{subexp} @var{facename} @var{override} @var{laxmatch})
+@end example
+
+However, instead of specifying the value @var{facename} to use for the
+@code{face} property, it specifies the value @var{syntax} to use for the
+@code{syntax-table} property. Here, @var{syntax} can be a variable
+whose value is a syntax table, a syntax entry of the form
+@code{(@var{syntax-code} . @var{matching-char})}, or an expression whose
+value is one of those two types.
+@end defvar
+
@node Hooks
@section Hooks
@cindex hooks
Every major mode function is supposed to run a normal hook called the
@dfn{mode hook} as the last step of initialization. This makes it easy
for a user to customize the behavior of the mode, by overriding the
-local variable assignments already made by the mode. But hooks are used
-in other contexts too. For example, the hook @code{suspend-hook} runs
-just before Emacs suspends itself (@pxref{Suspending Emacs}).
+buffer-local variable assignments already made by the mode. But hooks
+are used in other contexts too. For example, the hook
+@code{suspend-hook} runs just before Emacs suspends itself
+(@pxref{Suspending Emacs}).
The recommended way to add a hook function to a normal hook is by
calling @code{add-hook} (see below). The hook functions may be any of
If the variable's name ends in @samp{-function}, then its value
is just a single function, not a list of functions.
- Here's an expression that uses a mode hook to turn on Auto Fill mode
-when in Lisp Interaction mode:
+ Here's an example that uses a mode hook to turn on Auto Fill mode when
+in Lisp Interaction mode:
@example
(add-hook 'lisp-interaction-mode-hook 'turn-on-auto-fill)
-@end example
-
- The next example shows how to use a hook to customize the way Emacs
-formats C code. (People often have strong personal preferences for one
-format or another.) Here the hook function is an anonymous lambda
-expression.
-
-@cindex lambda expression in hook
-@example
-@group
-(add-hook 'c-mode-hook
- (function (lambda ()
- (setq c-indent-level 4
- c-argdecl-indent 0
- c-label-offset -4
-@end group
-@group
- c-continued-statement-indent 0
- c-brace-offset 0
- comment-column 40))))
-
-(setq c++-mode-hook c-mode-hook)
-@end group
@end example
At the appropriate time, Emacs uses the @code{run-hooks} function to
are executed does not matter. Any dependence on the order is ``asking
for trouble.'' However, the order is predictable: normally,
@var{function} goes at the front of the hook list, so it will be
-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.
+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
+function buffer-local in 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
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.
+from the buffer-local hook list instead of from the global hook list.
+If the hook variable itself is not buffer-local, then the value of
+@var{local} makes no difference.
@end defun
@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.
+This function makes the hook variable @code{hook} buffer-local in the
+current buffer. When a hook variable is buffer-local, it can have
+buffer-local and global hook functions, and @code{run-hooks} runs all of
+them.
This function works by making @code{t} an element of the buffer-local
value. That serves as a flag to use the hook functions in the default
-value of the hook variable as well as those in the local value. Since
-@code{run-hooks} understands this flag, @code{make-local-hook} works
-with all normal hooks. It works for only some non-normal hooks---those
-whose callers have been updated to understand this meaning of @code{t}.
+value of the hook variable as well as those in the buffer-local value.
+Since @code{run-hooks} understands this flag, @code{make-local-hook}
+works with all normal hooks. It works for only some non-normal
+hooks---those whose callers have been updated to understand this meaning
+of @code{t}.
Do not use @code{make-local-variable} directly for hook variables; it is
not sufficient.
* Scanning Charsets::
* Chars and Bytes::
* Coding Systems::
+* Lisp and Coding System::
* Default Coding Systems::
* Specifying Coding Systems::
* Explicit Encoding::
+* MS-DOS File Types::
+* MS-DOS Subprocesses::
@end menu
@node Text Representations
In unibyte representation, each character occupies one byte and
therefore the possible character codes range from 0 to 255. Codes 0
through 127 are @sc{ASCII} characters; the codes from 128 through 255
-are used for one non-@sc{ASCII} character set (you can choose which one
-by setting the variable @code{nonascii-insert-offset}).
+are used for one non-@sc{ASCII} character set (you can choose which
+character set by setting the variable @code{nonascii-insert-offset}).
@cindex leading code
@cindex multibyte text
If it is non-@code{nil}, the buffer contains multibyte text; otherwise,
it contains unibyte text.
-@strong{Warning:} do not set this variable directly; instead, use the
-function @code{set-buffer-multibyte} to change a buffer's
-representation.
+You cannot set this variable directly; instead, use the function
+@code{set-buffer-multibyte} to change a buffer's representation.
@end defvar
@tindex default-enable-multibyte-characters
the characters that might be in the multibyte text. The other natural
alternative, to convert the buffer contents to multibyte, is not
acceptable because the buffer's representation is a choice made by the
-user that cannot simply be overrided.
+user that cannot be overridden automatically.
Converting unibyte text to multibyte text leaves @sc{ASCII} characters
-unchanged. It converts the non-@sc{ASCII} codes 128 through 255 by
-adding the value @code{nonascii-insert-offset} to each character code.
-By setting this variable, you specify which character set the unibyte
-characters correspond to. For example, if @code{nonascii-insert-offset}
-is 2048, which is @code{(- (make-char 'latin-iso8859-1 0) 128)}, then
-the unibyte non-@sc{ASCII} characters correspond to Latin 1. If it is
-2688, which is @code{(- (make-char 'greek-iso8859-7 0) 128)}, then they
-correspond to Greek letters.
+unchanged, and likewise 128 through 159. It converts the non-@sc{ASCII}
+codes 160 through 255 by adding the value @code{nonascii-insert-offset}
+to each character code. By setting this variable, you specify which
+character set the unibyte characters correspond to. For example, if
+@code{nonascii-insert-offset} is 2048, which is @code{(- (make-char
+'latin-iso8859-1 0) 128)}, then the unibyte non-@sc{ASCII} characters
+correspond to Latin 1. If it is 2688, which is @code{(- (make-char
+'greek-iso8859-7 0) 128)}, then they correspond to Greek letters.
Converting multibyte text to unibyte is simpler: it performs
logical-and of each character code with 255. If
@code{nonascii-insert-offset}. You can use it to specify independently
how to translate each code in the range of 128 through 255 into a
multibyte character. The value should be a vector, or @code{nil}.
+If this is non-@code{nil}, it overrides @code{nonascii-insert-offset}.
@end defvar
@tindex string-make-unibyte
@defun string-make-unibyte string
This function converts the text of @var{string} to unibyte
representation, if it isn't already, and return the result. If
-conversion does not change the contents, the value may be @var{string}
-itself.
+@var{string} is a unibyte string, it is returned unchanged.
@end defun
@tindex string-make-multibyte
@defun string-make-multibyte string
This function converts the text of @var{string} to multibyte
representation, if it isn't already, and return the result. If
-conversion does not change the contents, the value may be @var{string}
-itself.
+@var{string} is a multibyte string, it is returned unchanged.
@end defun
@node Selecting a Representation
This function sets @code{enable-multibyte-characters} to record which
representation is in use. It also adjusts various data in the buffer
-(including its overlays, text properties and markers) so that they
-cover or fall between the same text as they did before.
+(including overlays, text properties and markers) so that they cover the
+same text as they did before.
@end defun
@tindex string-as-unibyte
treating each byte as a character. This means that the value may have
more characters than @var{string} has.
-If @var{string} is unibyte already, then the value may be @var{string}
+If @var{string} is unibyte already, then the value is @var{string}
itself.
@end defun
treating each multibyte sequence as one character. This means that the
value may have fewer characters than @var{string} has.
-If @var{string} is multibyte already, then the value may be @var{string}
+If @var{string} is multibyte already, then the value is @var{string}
itself.
@end defun
0 to 255---the values that can fit in one byte. The valid character
codes for multibyte representation range from 0 to 524287, but not all
values in that range are valid. In particular, the values 128 through
-255 are not valid in multibyte text. Only the @sc{ASCII} codes 0
-through 127 are used in both representations.
+255 are not legitimate in multibyte text (though they can occur in ``raw
+bytes''; @pxref{Explicit Encoding}). Only the @sc{ASCII} codes 0
+through 127 are fully legitimate in both representations.
@defun char-valid-p charcode
This returns @code{t} if @var{charcode} is valid for either one of the two
In general, there is one character set for each distinct script. For
example, @code{latin-iso8859-1} is one character set,
@code{greek-iso8859-7} is another, and @code{ascii} is another. An
-Emacs character set can hold at most 9025 characters; therefore. in some
-cases, a set of characters that would logically be grouped together are
-split into several character sets. For example, one set of Chinese
-characters is divided into eight Emacs character sets,
-@code{chinese-cns11643-1} through @code{chinese-cns11643-7}.
+Emacs character set can hold at most 9025 characters; therefore, in some
+cases, characters that would logically be grouped together are split
+into several character sets. For example, one set of Chinese characters
+is divided into eight Emacs character sets, @code{chinese-cns11643-1}
+through @code{chinese-cns11643-7}.
@tindex charsetp
@defun charsetp object
In multibyte representation, each character occupies one or more
bytes. The functions in this section convert between characters and the
-byte values used to represent them.
+byte values used to represent them. For most purposes, there is no need
+to be concerned with the number of bytes used to represent a character
+because Emacs translates automatically when necessary.
@tindex char-bytes
@defun char-bytes character
This function returns the number of bytes used to represent the
character @var{character}. In most cases, this is the same as
@code{(length (split-char @var{character}))}; the only exception is for
-ASCII characters, which use just one byte.
+ASCII characters and the codes used in unibyte text, which use just one
+byte.
@example
(char-bytes 2248)
characters; for example, there are three coding systems for the Cyrillic
(Russian) alphabet: ISO, Alternativnyj, and KOI8.
-@cindex end of line conversion
- @dfn{End of line conversion} handles three different conventions used
-on various systems for end of line. The Unix convention is to use the
-linefeed character (also called newline). The DOS convention is to use
-the two character sequence, carriage-return linefeed, at the end of a
-line. The Mac convention is to use just carriage-return.
-
Most coding systems specify a particular character code for
conversion, but some of them leave this unspecified---to be chosen
heuristically based on the data.
+@cindex end of line conversion
+ @dfn{End of line conversion} handles three different conventions used
+on various systems for representing end of line in files. The Unix
+convention is to use the linefeed character (also called newline). The
+DOS convention is to use the two character sequence, carriage-return
+linefeed, at the end of a line. The Mac convention is to use just
+carriage-return.
+
@cindex base coding system
@cindex variant coding system
@dfn{Base coding systems} such as @code{latin-1} leave the end-of-line
well. Each base coding system has three corresponding variants whose
names are formed by adding @samp{-unix}, @samp{-dos} and @samp{-mac}.
+@node Lisp and Coding Systems
+@subsection Coding Systems in Lisp
+
Here are Lisp facilities for working with coding systems;
@tindex coding-system-list
Otherwise it signals an error with condition @code{coding-system-error}.
@end defun
+@tindex find-safe-coding-system
+@defun find-safe-coding-system from to
+Return a list of proper coding systems to encode a text between
+@var{from} and @var{to}. All coding systems in the list can safely
+encode any multibyte characters in the text.
+
+If the text contains no multibyte characters, return a list of a single
+element @code{undecided}.
+@end defun
+
@tindex detect-coding-region
@defun detect-coding-region start end highest
This function chooses a plausible coding system for decoding the text
from @var{start} to @var{end}. This text should be ``raw bytes''
-(@pxref{Specifying Coding Systems}).
+(@pxref{Explicit Encoding}).
Normally this function returns is a list of coding systems that could
handle decoding the text that was scanned. They are listed in order of
@code{process-coding-system-alist}, or
@code{network-coding-system-alist}, depending on @var{operation}.
@xref{Default Coding Systems}.
+@end defun
+
+ Here are two functions you can use to let the user specify a coding
+system, with completion. @xref{Completion}.
+
+@tindex read-coding-system
+@defun read-coding-system prompt default
+This function reads a coding system using the minibuffer, prompting with
+string @var{prompt}, and returns the coding system name as a symbol. If
+the user enters null input, @var{default} specifies which coding system
+to return. It should be a symbol or a string.
+@end defun
+
+@tindex read-non-nil-coding-system
+@defun read-non-nil-coding-system prompt
+This function reads a coding system using the minibuffer, prompting with
+string @var{prompt},and returns the coding system name as a symbol. If
+the user tries to enter null input, it asks the user to try again.
+@xref{Coding Systems}.
@end defun
@node Default Coding Systems
certain files or when running certain subprograms. The idea of these
variables is that you set them once and for all to the defaults you
want, and then do not change them again. To specify a particular coding
-system for a particular operation, don't change these variables;
-instead, override them using @code{coding-system-for-read} and
-@code{coding-system-for-write} (@pxref{Specifying Coding Systems}).
+system for a particular operation in a Lisp program, don't change these
+variables; instead, override them using @code{coding-system-for-read}
+and @code{coding-system-for-write} (@pxref{Specifying Coding Systems}).
@tindex file-coding-system-alist
@defvar file-coding-system-alist
@defvar network-coding-system-alist
This variable is an alist that specifies the coding system to use for
network streams. It works much like @code{file-coding-system-alist},
-with the difference that the @var{pattern} in an elemetn may be either a
+with the difference that the @var{pattern} in an element may be either a
port number or a regular expression. If it is a regular expression, it
is matched against the network service name used to open the network
stream.
@example
;; @r{Read the file with no character code conversion.}
-;; @r{Assume CRLF represents end-of-line.}
+;; @r{Assume @sc{crlf} represents end-of-line.}
(let ((coding-system-for-write 'emacs-mule-dos))
(insert-file-contents filename))
@end example
@tindex last-coding-system-used
@defvar last-coding-system-used
-All operations that use a coding system set this variable
+All I/O operations that use a coding system set this variable
to the coding system name that was used.
@end defvar
way that an external file would. When a buffer contains raw bytes, it
is most natural to mark that buffer as using unibyte representation,
using @code{set-buffer-multibyte} (@pxref{Selecting a Representation}),
-but this is not required.
+but this is not required. If the buffer's contents are only temporarily
+raw, leave the buffer multibyte, which will be correct after you decode
+them.
The usual way to get raw bytes in a buffer, for explicit decoding, is
-to read them with from a file with @code{insert-file-contents-literally}
+to read them from a file with @code{insert-file-contents-literally}
(@pxref{Reading from Files}) or specify a non-@code{nil} @var{rawfile}
-arguments when visiting a file with @code{find-file-noselect}.
+argument when visiting a file with @code{find-file-noselect}.
The usual way to use the raw bytes that result from explicitly
encoding text is to copy them to a file or process---for example, to
-write it with @code{write-region} (@pxref{Writing to Files}), and
+write them with @code{write-region} (@pxref{Writing to Files}), and
suppress encoding for that @code{write-region} call by binding
@code{coding-system-for-write} to @code{no-conversion}.
@tindex encode-coding-region
@defun encode-coding-region start end coding-system
This function encodes the text from @var{start} to @var{end} according
-to coding system @var{coding-system}. The encoded text replaces
-the original text in the buffer. The result of encoding is
-``raw bytes.''
+to coding system @var{coding-system}. The encoded text replaces the
+original text in the buffer. The result of encoding is ``raw bytes,''
+but the buffer remains multibyte if it was multibyte before.
@end defun
@tindex encode-coding-string
@defun encode-coding-string string coding-system
This function encodes the text in @var{string} according to coding
system @var{coding-system}. It returns a new string containing the
-encoded text. The result of encoding is ``raw bytes.''
+encoded text. The result of encoding is a unibyte string of ``raw bytes.''
@end defun
@tindex decode-coding-region
decoded text. To make explicit decoding useful, the contents of
@var{string} ought to be ``raw bytes.''
@end defun
+
+@node MS-DOS File Types
+@section MS-DOS File Types
+@cindex DOS file types
+@cindex MS-DOS file types
+@cindex Windows file types
+@cindex file types on MS-DOS and Windows
+@cindex text files and binary files
+@cindex binary files and text files
+
+ Emacs on MS-DOS and on MS-Windows recognizes certain file names as
+text files or binary files. For a text file, Emacs always uses DOS
+end-of-line conversion. For a binary file, Emacs does no end-of-line
+conversion and no character code conversion.
+
+@defvar buffer-file-type
+This variable, automatically buffer-local in each buffer, records the
+file type of the buffer's visited file. The value is @code{nil} for
+text, @code{t} for binary. When a buffer does not specify a coding
+system with @code{buffer-file-coding-system}, this variable is used by
+the function @code{find-buffer-file-type-coding-system} to determine
+which coding system to use when writing the contents of the buffer.
+@end defvar
+
+@defopt file-name-buffer-file-type-alist
+This variable holds an alist for recognizing text and binary files.
+Each element has the form (@var{regexp} . @var{type}), where
+@var{regexp} is matched against the file name, and @var{type} may be
+@code{nil} for text, @code{t} for binary, or a function to call to
+compute which. If it is a function, then it is called with a single
+argument (the file name) and should return @code{t} or @code{nil}.
+
+Emacs when running on MS-DOS or MS-Windows checks this alist to decide
+which coding system to use when reading a file. For a text file,
+@code{undecided-dos} is used. For a binary file, @code{no-conversion}
+is used.
+
+If no element in this alist matches a given file name, then
+@code{default-buffer-file-type} says how to treat the file.
+@end defopt
+
+@defopt default-buffer-file-type
+This variable says how to handle files for which
+@code{file-name-buffer-file-type-alist} says nothing about the type.
+
+If this variable is non-@code{nil}, then these files are treated as
+binary. Otherwise, nothing special is done for them---the coding system
+is deduced solely from the file contents, in the usual Emacs fashion.
+@end defopt
+
+@node MS-DOS Subprocesses
+@section MS-DOS Subprocesses
+
+ On Microsoft operating systems, these variables provide an alternative
+way to specify the kind of end-of-line conversion to use for input and
+output. The variable @code{binary-process-input} applies to input sent
+to the subprocess, and @code{binary-process-output} applies to output
+received from it. A non-@code{nil} value means the data is ``binary,''
+and @code{nil} means the data is text.
+
+@defvar binary-process-input
+If this variable is @code{nil}, convert newlines to @sc{crlf} sequences in
+the input to a synchronous subprocess.
+@end defvar
+
+@defvar binary-process-output
+If this variable is @code{nil}, convert @sc{crlf} sequences to newlines in
+the output from a synchronous subprocess.
+@end defvar
@dfn{floating point numbers}. Integers are whole numbers such as
@minus{}3, 0, 7, 13, and 511. Their values are exact. Floating point
numbers are numbers with fractional parts, such as @minus{}4.5, 0.0, or
-2.71828. They can also be expressed in exponential notation:
-1.5e2 equals 150; in this example, @samp{e2} stands for ten to the
-second power, and is multiplied by 1.5. Floating point values are not
+2.71828. They can also be expressed in exponential notation: 1.5e2
+equals 150; in this example, @samp{e2} stands for ten to the second
+power, and that is multiplied by 1.5. Floating point values are not
exact; they have a fixed, limited amount of precision.
@menu
there is no correct answer. For example, @code{(sqrt -1.0)} returns a
NaN. For practical purposes, there's no significant difference between
different NaN values in Emacs Lisp, and there's no rule for precisely
-which NaN value should be used in a particular case, so this manual
+which NaN value should be used in a particular case, so Emacs Lisp
doesn't try to distinguish them. Here are the read syntaxes for
-these numbers:
+these special floating point values:
@table @asis
@item positive infinity
@samp{0.0e+NaN}.
@end table
+ In addition, the value @code{-0.0} is distinguishable from ordinary
+zero in IEEE floating point (although @code{equal} and @code{=} consider
+them equal values).
+
You can use @code{logb} to extract the binary exponent of a floating
point number (or estimate the logarithm of an integer):
@end example
@end defun
+@defun abs number
+This returns the absolute value of @var{number}.
+@end defun
+
@node Numeric Conversions
@section Numeric Conversions
@cindex rounding in conversions
All of these functions except @code{%} return a floating point value
if any argument is floating.
- It is important to note that in GNU Emacs Lisp, arithmetic functions
+ It is important to note that in Emacs Lisp, arithmetic functions
do not check for overflow. Thus @code{(1+ 134217727)} may evaluate to
@minus{}134217728, depending on your hardware.
This function returns @var{number-or-marker} minus 1.
@end defun
-@defun abs number
-This returns the absolute value of @var{number}.
-@end defun
-
@defun + &rest numbers-or-markers
This function adds its arguments together. When given no arguments,
@code{+} returns 0.
machines round in the standard fashion.
@cindex @code{arith-error} in division
-If you divide by 0, an @code{arith-error} error is signaled.
-(@xref{Errors}.)
+If you divide an integer by 0, an @code{arith-error} error is signaled.
+(@xref{Errors}.) Floating point division by zero returns either
+infinity or a NaN if your machine supports IEEE floating point;
+otherwise, it signals an @code{arith-error} error.
@example
@group
@end group
(/ 5 2)
@result{} 2
+(/ 5.0 2)
+ @result{} 2.5
+(/ 5 2.0)
+ @result{} 2.5
+(/ 5.0 2.0)
+ @result{} 2.5
(/ 25 3 2)
@result{} 4
(/ -17 6)
@cindex transcendental functions
@cindex mathematical functions
-These mathematical functions are available if floating point is
-supported. They allow integers as well as floating point numbers
-as arguments.
+ These mathematical functions allow integers as well as floating point
+numbers as arguments.
@defun sin arg
@defunx cos arg
which all other types are constructed, are called @dfn{primitive
types}. Each object belongs to one and only one primitive type. These
types include @dfn{integer}, @dfn{float}, @dfn{cons}, @dfn{symbol},
-@dfn{string}, @dfn{vector}, @dfn{subr}, @dfn{byte-code function}, and
+@dfn{string}, @dfn{vector}, @dfn{subr}, @dfn{byte-code function}, plus
several special types, such as @dfn{buffer}, that are related to
editing. (@xref{Editing Types}.)
object. @xref{Read and Print}.
Most objects have more than one possible read syntax. Some types of
-object have no read syntax; except for these cases, the printed
-representation of an object is also a read syntax for it.
+object have no read syntax, since it may not make sense to enter objects
+of these types directly in a Lisp program. Except for these cases, the
+printed representation of an object is also a read syntax for it.
In other languages, an expression is text; it has no other form. In
Lisp, an expression is primarily a Lisp object and only secondarily the
@cindex hash notation
Every type has a printed representation. Some types have no read
-syntax, since it may not make sense to enter objects of these types
-directly in a Lisp program. For example, the buffer type does not have
-a read syntax. Objects of these types are printed in @dfn{hash
-notation}: the characters @samp{#<} followed by a descriptive string
-(typically the type name followed by the name of the object), and closed
-with a matching @samp{>}. Hash notation cannot be read at all, so the
-Lisp reader signals the error @code{invalid-read-syntax} whenever it
-encounters @samp{#<}.
+syntax---for example, the buffer type has none. Objects of these types
+are printed in @dfn{hash notation}: the characters @samp{#<} followed by
+a descriptive string (typically the type name followed by the name of
+the object), and closed with a matching @samp{>}. Hash notation cannot
+be read at all, so the Lisp reader signals the error
+@code{invalid-read-syntax} whenever it encounters @samp{#<}.
@kindex invalid-read-syntax
@example
1 ; @r{The integer 1.}
1. ; @r{Also The integer 1.}
+1 ; @r{Also the integer 1.}
-268435457 ; @r{Also the integer 1!}
- ; @r{ (on a 28-bit implementation)}
+268435457 ; @r{Also the integer 1 on a 28-bit implementation.}
@end group
@end example
Characters in strings, buffers, and files are currently limited to the
range of 0 to 524287---nineteen bits. But not all values in that range
-are valid character codes. Characters that represent keyboard input
-have a much wider range, so they can modifier keys such as Control, Meta
-and Shift.
+are valid character codes. Codes 0 through 127 are ASCII codes; the
+rest are non-ASCII (@pxref{Non-ASCII Characters}). Characters that represent
+keyboard input have a much wider range, to encode modifier keys such as
+Control, Meta and Shift.
@cindex read syntax for characters
@cindex printed representation for characters
?\a @result{} 7 ; @r{@kbd{C-g}}
?\b @result{} 8 ; @r{backspace, @key{BS}, @kbd{C-h}}
?\t @result{} 9 ; @r{tab, @key{TAB}, @kbd{C-i}}
-?\n @result{} 10 ; @r{newline, @key{LFD}, @kbd{C-j}}
+?\n @result{} 10 ; @r{newline, @kbd{C-j}}
?\v @result{} 11 ; @r{vertical tab, @kbd{C-k}}
?\f @result{} 12 ; @r{formfeed character, @kbd{C-l}}
?\r @result{} 13 ; @r{carriage return, @key{RET}, @kbd{C-m}}
that exist in @sc{ASCII}; but for keyboard input purposes, you can turn
any character into a control character with @samp{C-}. The character
codes for these non-@sc{ASCII} control characters include the
-@iftex
+@tex
$2^{26}$
-@end iftex
+@end tex
@ifinfo
2**26
@end ifinfo
@noindent
As a result, it is currently not possible to represent the character
-@kbd{Control-?}, which is a meaningful input character under X. It is
-not easy to change this as various Lisp files refer to @key{DEL} in this
-way.
+@kbd{Control-?}, which is a meaningful input character under X, using
+@samp{\C-}. It is not easy to change this, as various Lisp files refer
+to @key{DEL} in this way.
For representing control characters to be found in files or strings,
we recommend the @samp{^} syntax; for control characters in keyboard
-input, we prefer the @samp{C-} syntax. This does not affect the meaning
-of the program, but may guide the understanding of people who read it.
+input, we prefer the @samp{C-} syntax. Which one you use does not
+affect the meaning of the program, but may guide the understanding of
+people who read it.
@cindex meta characters
A @dfn{meta character} is a character typed with the @key{META}
modifier key. The integer that represents such a character has the
-@iftex
+@tex
$2^{27}$
-@end iftex
+@end tex
@ifinfo
2**27
@end ifinfo
of basic character codes.
In a string, the
-@iftex
+@tex
$2^{7}$
-@end iftex
+@end tex
@ifinfo
2**7
@end ifinfo
for example, @sc{ASCII} distinguishes between the characters @samp{a}
and @samp{A}. But @sc{ASCII} has no way to represent whether a control
character is upper case or lower case. Emacs uses the
-@iftex
+@tex
$2^{25}$
-@end iftex
+@end tex
@ifinfo
2**25
@end ifinfo
-bit to indicate that the shift key was used for typing a control
+bit to indicate that the shift key was used in typing a control
character. This distinction is possible only when you use X terminals
-or other special terminals; ordinary terminals do not indicate the
+or other special terminals; ordinary terminals do not report the
distinction to the computer in any way.
@cindex hyper characters
in a character: @dfn{hyper}, @dfn{super} and @dfn{alt}. The syntaxes
for these bits are @samp{\H-}, @samp{\s-} and @samp{\A-}. Thus,
@samp{?\H-\M-\A-x} represents @kbd{Alt-Hyper-Meta-x}.
-@iftex
+@tex
Numerically, the
bit values are $2^{22}$ for alt, $2^{23}$ for super and $2^{24}$ for hyper.
-@end iftex
+@end tex
@ifinfo
Numerically, the
bit values are 2**22 for alt, 2**23 for super and 2**24 for hyper.
Thus, @samp{?\x41} for the character @kbd{A}, @samp{?\x1} for the
character @kbd{C-a}, and @code{?\x8c0} for the character
@iftex
-@`a.
+@samp{@`a}.
@end iftex
@ifinfo
@samp{a} with grave accent.
the name of a symbol simply quotes the single character that follows the
backslash. For example, in a string, @samp{\t} represents a tab
character; in the name of a symbol, however, @samp{\t} merely quotes the
-letter @kbd{t}. To have a symbol with a tab character in its name, you
+letter @samp{t}. To have a symbol with a tab character in its name, you
must actually use a tab (preceded with a backslash). But it's rare to
do such a thing.
arrays. Thus, an object of type list or of type array is also
considered a sequence.
- Arrays are further subdivided into strings and vectors. Vectors can
-hold elements of any type, but string elements must be characters in the
-range from 0 to 255. However, the characters in a string can have text
-properties like characters in a buffer (@pxref{Text Properties});
-vectors do not support text properties even when their elements happen
-to be characters.
-
- Lists, strings and vectors are different, but they have important
-similarities. For example, all have a length @var{l}, and all have
-elements which can be indexed from zero to @var{l} minus one. Also,
-several functions, called sequence functions, accept any kind of
+ Arrays are further subdivided into strings, vectors, char-tables and
+bool-vectors. Vectors can hold elements of any type, but string
+elements must be characters, and bool-vector elements must be @code{t}
+or @code{nil}. The characters in a string can have text properties like
+characters in a buffer (@pxref{Text Properties}); vectors and
+bool-vectors do not support text properties even when their elements
+happen to be characters. Char-tables are like vectors except that they
+are indexed by any valid character code.
+
+ Lists, strings and the other array types are different, but they have
+important similarities. For example, all have a length @var{l}, and all
+have elements which can be indexed from zero to @var{l} minus one.
+Several functions, called sequence functions, accept any kind of
sequence. For example, the function @code{elt} can be used to extract
an element of a sequence, given its index. @xref{Sequences Arrays
Vectors}.
- It is impossible to read the same sequence twice, since sequences are
-always created anew upon reading. If you read the read syntax for a
-sequence twice, you get two sequences with equal contents. There is one
-exception: the empty list @code{()} always stands for the same object,
-@code{nil}.
+ It is generally impossible to read the same sequence twice, since
+sequences are always created anew upon reading. If you read the read
+syntax for a sequence twice, you get two sequences with equal contents.
+There is one exception: the empty list @code{()} always stands for the
+same object, @code{nil}.
@node Cons Cell Type
@subsection Cons Cell and List Types
@example
@group
- ___ ___ ___ ___ ___ ___
- |___|___|--> |___|___|--> |___|___|--> nil
+ --- --- --- --- --- ---
+ | | |--> | | |--> | | |--> nil
+ --- --- --- --- --- ---
| | |
| | |
--> rose --> violet --> buttercup
@example
@group
- ___ ___ ___ ___
- |___|___|--> |___|___|--> nil
+ --- --- --- ---
+ | | |--> | | |--> nil
+ --- --- --- ---
| |
| |
--> A --> nil
@example
@group
- ___ ___
- |___|___|--> violet
+ --- ---
+ | | |--> violet
+ --- ---
|
|
--> rose
@example
@group
- ___ ___ ___ ___
- |___|___|--> |___|___|--> buttercup
+ --- --- --- ---
+ | | |--> | | |--> buttercup
+ --- --- --- ---
| |
| |
--> rose --> violet
@example
@group
- ___ ___ ___ ___
- |___|___|--> |___|___|--> nil
+ --- --- --- ---
+ | | |--> | | |--> nil
+ --- --- --- ---
| |
| |
--> rose --> violet
@example
@group
- ___ ___ ___ ___ ___ ___
- |___|___|--> |___|___|--> |___|___|--> nil
+ --- --- --- --- --- ---
+ | | |--> | | |--> | | |--> nil
+ --- --- --- --- --- ---
| | |
| | |
--> rose --> violet --> buttercup
An @dfn{array} is composed of an arbitrary number of slots for
referring to other Lisp objects, arranged in a contiguous block of
-memory. Accessing any element of an array takes the same amount of
-time. In contrast, accessing an element of a list requires time
-proportional to the position of the element in the list. (Elements at
-the end of a list take longer to access than elements at the beginning
-of a list.)
-
- Emacs defines two types of array, strings and vectors. A string is an
-array of characters and a vector is an array of arbitrary objects. Both
-are one-dimensional. (Most other programming languages support
-multidimensional arrays, but they are not essential; you can get the
-same effect with an array of arrays.) Each type of array has its own
-read syntax; see @ref{String Type}, and @ref{Vector Type}.
-
- An array may have any length up to the largest integer; but once
-created, it has a fixed size. The first element of an array has index
-zero, the second element has index 1, and so on. This is called
-@dfn{zero-origin} indexing. For example, an array of four elements has
-indices 0, 1, 2, @w{and 3}.
-
- The array type is contained in the sequence type and contains both the
-string type and the vector type.
+memory. Accessing any element of an array takes approximately the same
+amount of time. In contrast, accessing an element of a list requires
+time proportional to the position of the element in the list. (Elements
+at the end of a list take longer to access than elements at the
+beginning of a list.)
+
+ Emacs defines four types of array: strings, vectors, bool-vectors, and
+char-tables.
+
+ A string is an array of characters and a vector is an array of
+arbitrary objects. A bool-vector can hold only @code{t} or @code{nil}.
+These kinds of array may have any length up to the largest integer.
+Char-tables are sparse arrays indexed by any valid character code; they
+can hold arbitrary objects.
+
+ The first element of an array has index zero, the second element has
+index 1, and so on. This is called @dfn{zero-origin} indexing. For
+example, an array of four elements has indices 0, 1, 2, @w{and 3}. The
+largest possible index value is one less than the length of the array.
+Once an array is created, its length is fixed.
+
+ All Emacs Lisp arrays are one-dimensional. (Most other programming
+languages support multidimensional arrays, but they are not essential;
+you can get the same effect with an array of arrays.) Each type of
+array has its own read syntax; see the following sections for details.
+
+ The array type is contained in the sequence type and
+contains the string type, the vector type, the bool-vector type, and the
+char-table type.
@node String Type
@subsection String Type
constant by writing it literally. There are two text representations
for non-@sc{ASCII} characters in Emacs strings (and in buffers): unibyte
and multibyte. If the string constant is read from a multibyte source,
-then the character is read as a multibyte character, and that makes the
-string multibyte. If the string constant is read from a unibyte source,
-then the character is read as unibyte and that makes the string unibyte.
+such as a multibyte buffer or string, or a file that would be visited as
+multibyte, then the character is read as a multibyte character, and that
+makes the string multibyte. If the string constant is read from a
+unibyte source, then the character is read as unibyte and that makes the
+string unibyte.
+@c ??? Change this?
You can also represent a multibyte non-@sc{ASCII} character with its
character code, using a hex escape, @samp{\x@var{nnnnnnn}}, with as many
digits as necessary. (Multibyte non-@sc{ASCII} character codes are all
If you use the @samp{\M-} syntax to indicate a meta character in a
string constant, this sets the
-@iftex
+@tex
$2^{7}$
-@end iftex
+@end tex
@ifinfo
2**7
@end ifinfo
a whole character set.
The printed representation of a char-table is like a vector
-except that there is an extra @samp{#} at the beginning.
+except that there is an extra @samp{#^} at the beginning.
@xref{Char-Tables}, for special functions to operate on char-tables.
+Uses of char-tables include:
+
+@itemize @bullet
+@item
+Case tables (@pxref{Case Tables}).
+
+@item
+Character category tables (@pxref{Categories}).
+
+@item
+Display Tables (@pxref{Display Tables}).
+
+@item
+Syntax tables (@pxref{Syntax Tables}).
+@end itemize
@node Bool-Vector Type
@subsection Bool-Vector Type
@result{} #&3"\377"
(make-bool-vector 3 nil)
@result{} #&3"\0""
+;; @r{These are equal since only the first 3 bits are used.}
+(equal #&3"\377" #&3"\340")
+ @result{} t
@end example
@node Function Type
A @dfn{Lisp macro} is a user-defined construct that extends the Lisp
language. It is represented as an object much like a function, but with
-different parameter-passing semantics. A Lisp macro has the form of a
+different argument-passing semantics. A Lisp macro has the form of a
list whose first element is the symbol @code{macro} and whose @sc{cdr}
is a Lisp function object, including the @code{lambda} symbol.
(@pxref{Special Forms}).@refill
It does not matter to the caller of a function whether the function is
-primitive. However, this does matter if you try to substitute a
-function written in Lisp for a primitive of the same name. The reason
-is that the primitive function may be called directly from C code.
-Calls to the redefined function from Lisp will use the new definition,
-but calls from C code may still use the built-in definition. Therefore,
-@strong{we discourage redefinition of primitive functions}.
+primitive. However, this does matter if you try to redefine a primitive
+with a function written in Lisp. The reason is that the primitive
+function may be called directly from C code. Calls to the redefined
+function from Lisp will use the new definition, but calls from C code
+may still use the built-in definition. Therefore, @strong{we discourage
+redefinition of primitive functions}.
The term @dfn{function} refers to all Emacs functions, whether written
in Lisp or C. @xref{Function Type}, for information about the
@section Editing Types
@cindex editing types
- The types in the previous section are common to many Lisp dialects.
-Emacs Lisp provides several additional data types for purposes connected
-with editing.
+ The types in the previous section used for general programming
+purposes, and most of them are common to most Lisp dialects. Emacs Lisp
+provides several additional data types for purposes connected with
+editing.
@menu
* Buffer Type:: The basic object of editing.
* Window Type:: Buffers are displayed in windows.
* Frame Type:: Windows subdivide frames.
* Window Configuration Type:: Recording the way a frame is subdivided.
+* Frame Configuration Type:: Recording the status of all frames.
* Process Type:: A process running on the underlying OS.
* Stream Type:: Receive or send characters.
* Keymap Type:: What function a keystroke invokes.
-* Syntax Table Type:: What a character means.
-* Display Table Type:: How display tables are represented.
* Overlay Type:: How an overlay is represented.
@end menu
The contents of a buffer are much like a string, but buffers are not
used like strings in Emacs Lisp, and the available operations are
-different. For example, insertion of text into a buffer is very
-efficient, whereas ``inserting'' text into a string requires
+different. For example, you can insert text efficiently into an
+existing buffer, whereas ``inserting'' text into a string requires
concatenating substrings, and the result is an entirely new string
object.
a local keymap (@pxref{Keymaps}); and,
@item
-a local variable binding list (@pxref{Buffer-Local Variables}).
+a list of buffer-local variable bindings (@pxref{Buffer-Local Variables}).
@item
-a list of overlays (@pxref{Overlays}).
+overlays (@pxref{Overlays}).
@item
text properties for the text in the buffer (@pxref{Text Properties}).
programs.
A buffer may be @dfn{indirect}, which means it shares the text
-of another buffer. @xref{Indirect Buffers}.
+of another buffer, but presents it differently. @xref{Indirect Buffers}.
Buffers have no read syntax. They print in hash notation, showing the
buffer name.
@example
@group
(selected-frame)
- @result{} #<frame xemacs@@mole.gnu.ai.mit.edu 0xdac80>
+ @result{} #<frame emacs@@mole.gnu.ai.mit.edu 0xdac80>
@end group
@end example
Configurations}, for a description of several functions related to
window configurations.
+@node Frame Configuration Type
+@subsection Frame Configuration Type
+@cindex screen layout
+
+ A @dfn{frame configuration} stores information about the positions,
+sizes, and contents of the windows in all frames. It is actually
+a list whose @sc{car} is @code{frame-configuration} and whose
+@sc{cdr} is an alist. Each alist element describes one frame,
+which appears as the @sc{car} of that element.
+
+ @xref{Frame Configurations}, for a description of several functions
+related to frame configurations.
+
@node Process Type
@subsection Process Type
@xref{Keymaps}, for information about creating keymaps, handling prefix
keys, local as well as global keymaps, and changing key bindings.
-@node Syntax Table Type
-@subsection Syntax Table Type
-
- A @dfn{syntax table} is a char-table which specifies the syntax of
-each character, for word and list parsing. Each element of the syntax
-table defines how one character is interpreted when it appears in a
-buffer. For example, in C mode (@pxref{Major Modes}), the @samp{+}
-character is punctuation, but in Lisp mode it is a valid character in a
-symbol. These modes specify different interpretations by changing the
-syntax table entry for @samp{+}, at index 43 in the syntax table.
-
- Syntax tables are used only to control primitives that scan text in
-buffers, not for reading Lisp expressions. The syntax that the Lisp
-interpreter uses to read expressions is built into the Emacs source code
-and cannot be changed; thus, to change the list delimiters to be
-@samp{@{} and @samp{@}} instead of @samp{(} and @samp{)} would be
-impossible. (Some Lisp systems provide ways to redefine the read
-syntax, but we decided to leave this feature out of Emacs Lisp for
-simplicity.)
-
- @xref{Syntax Tables}, for details about syntax classes and how to make
-and modify syntax tables.
-
-@node Display Table Type
-@subsection Display Table Type
-
- A @dfn{display table} specifies how to display each character code.
-Each buffer and each window can have its own display table. A display
-table is actually a char-table. @xref{Display Tables}.
-
@node Overlay Type
@subsection Overlay Type
(setq list (append x list)))
@need 3000
(t
- ;; We only handle symbols and lists.
+ ;; We handle only symbols and lists.
(error "Invalid argument %s in add-on" x))))
@end example
@item arrayp
@xref{Array Functions, arrayp}.
+@item bool-vector-p
+@xref{Bool-Vectors, bool-vector-p}.
+
@item bufferp
@xref{Buffer Basics, bufferp}.
@xref{Byte-Code Type, byte-code-function-p}.
@item case-table-p
-@xref{Case Table, case-table-p}.
+@xref{Case Tables, case-table-p}.
@item char-or-string-p
@xref{Predicates for Strings, char-or-string-p}.
+@item char-table-p
+@xref{Char-Tables, char-table-p}.
+
@item commandp
@xref{Interactive Call, commandp}.
@item consp
@xref{List-related Predicates, consp}.
+@item display-table-p
+@xref{Display Tables, display-table-p}.
+
@item floatp
@xref{Predicates on Numbers, floatp}.
+@item frame-configuration-p
+@xref{Frame Configurations, frame-configuration-p}.
+
@item frame-live-p
@xref{Deleting Frames, frame-live-p}.
This function returns a symbol naming the primitive type of
@var{object}. The value is one of the symbols @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{process}, or
+@code{char-table}, @code{bool-vector}, @code{subr},
+@code{compiled-function}, @code{marker}, @code{overlay}, @code{window},
+@code{buffer}, @code{frame}, @code{process}, or
@code{window-configuration}.
@example
@code{eq} to each other: they are @code{eq} only if they are the same
object.
-(The @code{make-symbol} function returns an uninterned symbol that is
-not interned in the standard @code{obarray}. When uninterned symbols
-are in use, symbol names are no longer unique. Distinct symbols with
-the same name are not @code{eq}. @xref{Creating Symbols}.)
-
@example
@group
(eq 'foo 'foo)
@end group
@end example
+(The @code{make-symbol} function returns an uninterned symbol that is
+not interned in the standard @code{obarray}. When uninterned symbols
+are in use, symbol names are no longer unique. Distinct symbols with
+the same name are not @code{eq}. @xref{Creating Symbols}.)
+
+@example
+@group
+(eq (make-symbol "foo") 'foo)
+ @result{} nil
+@end group
+@end example
@end defun
@defun equal object1 object2
@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/os
-@node System Interface, Display, Processes, Top
+@node System Interface, Tips, Calendar, Top
@chapter Operating System Interface
This chapter is about starting and getting out of Emacs, access to
even earlier than this.)
@item
-It initializes the X window frame and faces, if appropriate.
+It initializes the window frame and faces, if appropriate.
@item
It runs the normal hook @code{before-init-hook}.
@cindex @file{site-start.el}
@item
-It loads the file @file{~/.emacs} unless @samp{-q} was specified on
-the command line. (This is not done in @samp{-batch} mode.) The @samp{-u}
-option can specify the user name whose home directory should be used
+It loads the file @file{~/.emacs}, unless @samp{-q} was specified on the
+command line. (This is not done in @samp{-batch} mode.) The @samp{-u}
+option can specify another user name whose home directory should be used
instead of @file{~}.
@item
-It loads the library @file{default} unless @code{inhibit-default-init}
+It loads the library @file{default}, unless @code{inhibit-default-init}
is non-@code{nil}. (This is not done in @samp{-batch} mode or if
@samp{-q} was specified on the command line.) The library's file name
is usually @file{default.el}.
systems, ``suspension'' actually creates a new shell temporarily as a
subprocess of Emacs. Then you would exit the shell to return to Emacs.
- Suspension is not useful with window systems such as X, because the
-Emacs job may not have a parent that can resume it again, and in any
-case you can give input to some other job such as a shell merely by
-moving to a different window. Therefore, suspending is not allowed
-when Emacs is an X client.
+ Suspension is not useful with window systems, because the Emacs job
+may not have a parent that can resume it again, and in any case you can
+give input to some other job such as a shell merely by moving to a
+different window. Therefore, suspending is not allowed when Emacs is using
+a window system.
@defun suspend-emacs string
This function stops Emacs and returns control to the superior process.
appear.
Before suspending, @code{suspend-emacs} runs the normal hook
-@code{suspend-hook}. In Emacs version 18, @code{suspend-hook} was not a
-normal hook; its value was a single function, and if its value was
-non-@code{nil}, then @code{suspend-emacs} returned immediately without
-actually suspending anything.
+@code{suspend-hook}.
After the user resumes Emacs, @code{suspend-emacs} runs the normal hook
@code{suspend-resume-hook}. @xref{Hooks}.
through various functions. These variables include the name of the
system, the user's @sc{uid}, and so on.
+@defvar system-configuration
+This variable holds the GNU configuration name for the hardware/software
+configuration of your system, as a string. The convenient way to test
+parts of this string is with @code{string-match}.
+@end defvar
+
@defvar system-type
The value of this variable is a symbol indicating the type of operating
system Emacs is operating on. Here is a table of the possible values:
Data General DGUX operating system.
@item gnu
-A GNU system (using the GNU kernel, which consists of the HURD and Mach).
+the GNU system (using the GNU kernel, which consists of the HURD and Mach).
@item gnu/linux
-A variant GNU system using the Linux kernel.
+A GNU/Linux system---that is, a variant GNU system, using the Linux
+kernel. (These systems are the ones people often call ``Linux,'' but
+actually Linux is just the kernel, not the whole system.)
@item hpux
Hewlett-Packard HPUX operating system.
systems.
@end defvar
-@defvar system-configuration
-This variable holds the GNU configuration name for the hardware/software
-configuration of your system, as a string. The convenient way to test
-parts of this string is with @code{string-match}.
-@end defvar
-
@defun system-name
This function returns the name of the machine you are running on.
@example
Time conversion functions always use the Gregorian calendar, even for
dates before the Gregorian calendar was introduced. Year numbers count
the number of years since the year 1 B.C., and do not skip zero as
-traditional Gregorian years do; for example, the year number -37
+traditional Gregorian years do; for example, the year number @minus{}37
represents the Gregorian year 38 B.C@.
@defun format-time-string format-string time
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 default locale (named C), it
-is equivalent to @samp{%D}.
+This has a locale-specific meaning. In the default locale (named
+@samp{C}), it is equivalent to @samp{%D}.
@item %X
-This has a locale-specific meaning. In the default locale (named C), it
-is equivalent to @samp{%T}.
+This has a locale-specific meaning. In the default locale (named
+@samp{C}), it is equivalent to @samp{%T}.
@item %y
This stands for the year without century (00-99).
@item %Y
@end table
You can also specify the field width and type of padding for any of
-these @samp{%}-constructs. This works as in @code{printf}: you write
-the field width as digits in the middle of a @samp{%}-construct. If you
+these @samp{%}-sequences. This works as in @code{printf}: you write
+the field width as digits in the middle of a @samp{%}-sequences. If you
start the field width with 0, it means to pad with zeros.
For example, @samp{%S} specifies the number of seconds since the minute;
Greenwich.
@end table
-Note that Common Lisp has different meanings for @var{dow} and
-@var{zone}.
+@strong{Common Lisp Note:} Common Lisp has different meanings for
+@var{dow} and @var{zone}.
@end defun
@defun encode-time seconds minutes hour day month year &optional @dots{}zone
You can set up a @dfn{timer} to call a function at a specified future time or
after a certain length of idleness.
- Emacs cannot run a timer at any arbitrary point in a Lisp program; it
+ Emacs cannot run timers at any arbitrary point in a Lisp program; it
can run them only when Emacs could accept output from a subprocess:
namely, while waiting or inside certain primitive functions such as
@code{sit-for} or @code{read-char} which @emph{can} wait. Therefore, a
later, and @var{args} are the arguments to give it when it is called.
The time @var{time} is specified as a string.
-Absolute times may be specified in a variety of formats; The form
+Absolute times may be specified in a wide variety of formats, and tries
+to accept all common date formats. One valid format is
@samp{@var{hour}:@var{min}:@var{sec} @var{timezone}
-@var{month}/@var{day}/@var{year}}, where all fields are numbers, works;
-the format that @code{current-time-string} returns is also allowed.
+@var{month}/@var{day}/@var{year}}, where all fields are numbers; the
+format that @code{current-time-string} returns is also allowed.
To specify a relative time, use numbers followed by units.
For example:
again.
Emacs can do various things while idle: garbage collect, autosave or
-handle data from a subprocess. But these interludes during idleness
-have little effect on idle timers. An idle timer set for 600 seconds
-will run when ten minutes have elapsed since the last user command was
-finished, even if subprocess output has been accepted thousands of times
-within those ten minutes, even if there have been garbage collections
-and autosaves.
+handle data from a subprocess. But these interludes during idleness do
+not interfere with idle timers, because they do not reset the clock of
+idleness to zero. An idle timer set for 600 seconds will run when ten
+minutes have elapsed since the last user command was finished, even if
+subprocess output has been accepted thousands of times within those ten
+minutes, even if there have been garbage collections and autosaves.
When the user supplies input, Emacs becomes non-idle while executing the
input. Then it becomes idle again, and all the idle timers that are
@defun set-input-mode interrupt flow meta quit-char
This function sets the mode for reading keyboard input. If
@var{interrupt} is non-null, then Emacs uses input interrupts. If it is
-@code{nil}, then it uses @sc{cbreak} mode. When Emacs communicates
-directly with X, it ignores this argument and uses interrupts if that is
-the way it knows how to communicate.
+@code{nil}, then it uses @sc{cbreak} mode. The default setting is
+system dependent. Some systems always use @sc{cbreak} mode regardless
+of what is specified.
-If @var{flow} is non-@code{nil}, then Emacs uses @sc{xon/xoff} (@kbd{C-q},
-@kbd{C-s}) flow control for output to the terminal. This has no effect except
-in @sc{cbreak} mode. @xref{Flow Control}.
+When Emacs communicates directly with X, it ignores this argument and
+uses interrupts if that is the way it knows how to communicate.
-The default setting is system dependent. Some systems always use
-@sc{cbreak} mode regardless of what is specified.
+If @var{flow} is non-@code{nil}, then Emacs uses @sc{xon/xoff}
+(@kbd{C-q}, @kbd{C-s}) flow control for output to the terminal. This
+has no effect except in @sc{cbreak} mode. @xref{Flow Control}.
@c Emacs 19 feature
The argument @var{meta} controls support for input character codes
Emacs disregards the 8th bit; this is necessary when the terminal uses
it as a parity bit. If @var{meta} is neither @code{t} nor @code{nil},
Emacs uses all 8 bits of input unchanged. This is good for terminals
-using European 8-bit character sets.
+that use 8-bit character sets.
@c Emacs 19 feature
If @var{quit-char} is non-@code{nil}, it specifies the character to
@code{nil}, Emacs is using @sc{cbreak} mode.
@item flow
is non-@code{nil} if Emacs uses @sc{xon/xoff} (@kbd{C-q}, @kbd{C-s})
-flow control for output to the terminal. This value has no effect
-unless @var{interrupt} is non-@code{nil}.
+flow control for output to the terminal. This value has effect when
+unless @var{interrupt} is @code{nil}.
@item meta
is @code{t} if Emacs treats the eighth bit of input characters as
the meta bit; @code{nil} means Emacs clears the eighth bit of every
other input events before they become part of key sequences. These
features apply to each event in the order they are described here: each
event is first modified according to @code{extra-keyboard-modifiers},
-then translated through @code{keyboard-translate-table} (if applicable).
-If it is being read as part of a key sequence, it is then added to the
-sequece being read; then subsequences containing it are checked first
-with @code{function-key-map} and then with @code{key-translation-map}.
+then translated through @code{keyboard-translate-table} (if applicable),
+and finally decoded with the specified keyboard coding system. If it is
+being read as part of a key sequence, it is then added to the sequence
+being read; then subsequences containing it are checked first with
+@code{function-key-map} and then with @code{key-translation-map}.
@c Emacs 19 feature
@defvar extra-keyboard-modifiers
Each time the user types a keyboard key, it is altered as if the
modifier keys specified in the bit mask were held down.
-When using X windows, the program can ``press'' any of the modifier
-keys in this way. Otherwise, only the @key{CTL} and @key{META} keys can
-be virtually pressed.
+When using a window system, the program can ``press'' any of the
+modifier keys in this way. Otherwise, only the @key{CTL} and @key{META}
+keys can be virtually pressed.
@end defvar
@defvar keyboard-translate-table
The remaining translation features translate subsequences of key
sequences being read. They are implemented in @code{read-key-sequence}
-and have no effect on @code{read-char}.
+and have no effect on input read with @code{read-event}.
@defvar function-key-map
This variable holds a keymap that describes the character sequences sent
key sequence, it is replaced with the events in @var{v}.
For example, VT100 terminals send @kbd{@key{ESC} O P} when the
-keypad PF1 key is pressed. Therefore, we want Emacs to translate
+keypad @key{PF1} key is pressed. Therefore, we want Emacs to translate
that sequence of events into the single event @code{pf1}. We accomplish
this by ``binding'' @kbd{@key{ESC} O P} to @code{[pf1]} in
@code{function-key-map}, when using a VT100.
Entries in @code{function-key-map} are ignored if they conflict with
bindings made in the minor mode, local, or global keymaps. The intent
is that the character sequences that function keys send should not have
-command bindings in their own right.
+command bindings in their own right---but if they do, the ordinary
+bindings take priority.
The value of @code{function-key-map} is usually set up automatically
according to the terminal's Terminfo or Termcap entry, but sometimes
terminal-specific files for many common terminals; their main purpose is
to make entries in @code{function-key-map} beyond those that can be
deduced from Termcap and Terminfo. @xref{Terminal-Specific}.
-
-Emacs versions 18 and earlier used totally different means of detecting
-the character sequences that represent function keys.
@end defvar
@defvar key-translation-map
@end group
@end example
-@pindex iso-transl
-@cindex Latin-1 character set (input)
-@cindex ISO Latin-1 characters (input)
-The @file{iso-transl} library uses this feature to provide a way of
-inputting non-ASCII Latin-1 characters.
+Finally, if you have enabled keyboard character set decoding using
+@code{set-keyboard-coding-system}, decoding is done after the
+translations listed above. @xref{Specifying Coding Systems}. In future
+Emacs versions, character set decoding may be done before the other
+translations.
@node Recording Input
@subsection Recording Input
@defun recent-keys
-This function returns a vector containing the last 100 input events
-from the keyboard or mouse. All input events are included, whether or
-not they were used as parts of key sequences. Thus, you always get the
-last 100 inputs, not counting keyboard macros. (Events from keyboard
-macros are excluded because they are less interesting for debugging; it
+This function returns a vector containing the last 100 input events from
+the keyboard or mouse. All input events are included, whether or not
+they were used as parts of key sequences. Thus, you always get the last
+100 input events, not counting events generated by keyboard macros.
+(These are excluded because they are less interesting for debugging; it
should be enough to see the events that invoked the macros.)
@end defun
than optimal. To fix the problem, set @code{baud-rate}.
@defun baud-rate
-This function returns the value of the variable @code{baud-rate}. In
-Emacs versions 18 and earlier, this was the only way to find out the
-terminal speed.
+This obsolete function returns the value of the variable
+@code{baud-rate}.
@end defun
@defun send-string-to-terminal string
This variable's value should be an alist with one element for each
system-specific keysym. An element has this form: @code{(@var{code}
. @var{symbol})}, where @var{code} is the numeric keysym code (not
-including the ``vendor specific'' bit, 1 << 28), and @var{symbol} is the
-name for the function key.
+including the ``vendor specific'' bit,
+@ifinfo
+-2**28,
+@end ifinfo
+@tex
+$-2^{28}$,
+@end tex
+and @var{symbol} is the name for the function key.
For example @code{(168 . mute-acute)} defines a system-specific key used
-by HP X servers whose numeric code is (1 << 28) + 168.
+by HP X servers whose numeric code is
+@ifinfo
+-2**28
+@end ifinfo
+@tex
+$-2^{28}$
+@end tex
++ 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.
+It is not crucial to exclude from the alist the keysyms of other X
+servers; those do no harm, as long as they don't conflict with the ones
+used by the X server actually in use.
The variable is always local to the current X terminal and cannot be
buffer-local. @xref{Multiple Displays}.
@section Flow Control
@cindex flow control characters
- This section attempts to answer the question ``Why does Emacs choose
-to use flow-control characters in its command character set?'' For a
-second view on this issue, read the comments on flow control in the
+ This section attempts to answer the question ``Why does Emacs use
+flow-control characters in its command character set?'' For a second
+view on this issue, read the comments on flow control in the
@file{emacs/INSTALL} file from the distribution; for help with Termcap
entries and DEC terminal concentrators, see @file{emacs/etc/TERMS}.
@cindex @kbd{C-q}
At one time, most terminals did not need flow control, and none used
@code{C-s} and @kbd{C-q} for flow control. Therefore, the choice of
-@kbd{C-s} and @kbd{C-q} as command characters was uncontroversial.
-Emacs, for economy of keystrokes and portability, used nearly all the
-@sc{ASCII} control characters, with mnemonic meanings when possible;
-thus, @kbd{C-s} for search and @kbd{C-q} for quote.
+@kbd{C-s} and @kbd{C-q} as command characters for searching and quoting
+was natural and uncontroversial. With so many commands needing key
+assignments. of course we assigned meanings to nearly all @sc{ASCII}
+control characters.
Later, some terminals were introduced which required these characters
for flow control. They were not very good terminals for full-screen
-editing, so Emacs maintainers did not pay attention. In later years,
-flow control with @kbd{C-s} and @kbd{C-q} became widespread among
-terminals, but by this time it was usually an option. And the majority
-of users, who can turn flow control off, were unwilling to switch to
-less mnemonic key bindings for the sake of flow control.
+editing, so Emacs maintainers ignored them. In later years, flow
+control with @kbd{C-s} and @kbd{C-q} became widespread among terminals,
+but by this time it was usually an option. And the majority of Emacs
+users, who can turn flow control off, did not want to switch to less
+mnemonic key bindings for the sake of flow control.
- So which usage is ``right'', Emacs's or that of some terminal and
+ So which usage is ``right''---Emacs's or that of some terminal and
concentrator manufacturers? This question has no simple answer.
One reason why we are reluctant to cater to the problems caused by
techniques (albeit less common in practice) for flow control that
preserve transparency of the character stream. Note also that their use
for flow control is not an official standard. Interestingly, on the
-model 33 teletype with a paper tape punch (which is very old), @kbd{C-s}
-and @kbd{C-q} were sent by the computer to turn the punch on and off!
+model 33 teletype with a paper tape punch (around 1970), @kbd{C-s} and
+@kbd{C-q} were sent by the computer to turn the punch on and off!
- As X servers and other window systems replace character-only
-terminals, this problem is gradually being cured. For the mean time,
-Emacs provides a convenient way of enabling flow control if you want it:
-call the function @code{enable-flow-control}.
+ As window systems and PC terminal emulators replace character-only
+terminals, the flow control problem is gradually disappearing. For the
+mean time, Emacs provides a convenient way of enabling flow control if
+you want it: call the function @code{enable-flow-control}.
@deffn Command enable-flow-control
This function enables use of @kbd{C-s} and @kbd{C-q} for output flow
In an interactive call, @var{n} is the numeric prefix argument,
if provided; otherwise @var{n} defaults to @code{nil}.
-Don't use this function in Lisp programs!
+@strong{Warning:} Don't use this function in Lisp programs!
@end deffn
@deffn Command end-of-buffer &optional n
In an interactive call, @var{n} is the numeric prefix argument,
if provided; otherwise @var{n} defaults to @code{nil}.
-Don't use this function in Lisp programs!
+@strong{Warning:} Don't use this function in Lisp programs!
@end deffn
@node Text Lines
@end example
@end defspec
+ Although @code{save-excursion} saves the location of the mark, it does
+not prevent functions which modify the buffer from setting
+@code{deactivate-mark}, and thus causing the deactivation of the mark
+after the command finishes. @xref{The Mark}.
+
@node Narrowing
@section Narrowing
@cindex narrowing
@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/processes
-@node Processes, System Interface, Abbrevs, Top
+@node Processes, Display, Abbrevs, Top
@chapter Processes
@cindex child process
@cindex parent process
@menu
* Subprocess Creation:: Functions that start subprocesses.
* Synchronous Processes:: Details of using synchronous subprocesses.
-* MS-DOS Subprocesses:: On MS-DOS, you must indicate text vs binary
- for data sent to and from a subprocess.
* Asynchronous Processes:: Starting up an asynchronous subprocess.
* Deleting Processes:: Eliminating an asynchronous subprocess.
* Process Information:: Accessing run-status and other attributes.
file name.
@end defopt
+@node Shell Arguments
+@section Shell Arguments
+
+ Lisp programs sometimes need to run a shell and give it a command
+which contains file names that were specified by the user. These
+programs ought to be able to support any valid file name. But the shell
+gives special treatment to certain characters, and if these characters
+occur in the file name, they will confuse the shell. To handle these
+characters, use the function @code{shell-quote-argument}:
+
+@defun shell-quote-argument argument
+This function returns a string which represents, in shell syntax,
+an argument whose actual contents are @var{argument}. It should
+work reliably to concatenate the return value into a shell command
+and then pass it to a shell for execution.
+
+Precisely what this function does depends on your operating system. The
+function is designed to work with the usual shell syntax; if you use an
+unusual shell, you will need to redefine this function. On MS-DOS, the
+function returns @var{argument} unchanged; while this is not really
+correct, it is the best one can do, since the MS-DOS shell has no
+quoting features.
+
+@example
+;; @r{This example shows the behavior on GNU and Unix systems.}
+(shell-quote-argument "foo > bar")
+ @result{} "foo\\ \\>\\ bar"
+@end example
+
+Here's an example of using @code{shell-quote-argument} to construct
+a shell command:
+
+@example
+(concat "diff -c "
+ (shell-quote-argument oldfile)
+ " "
+ (shell-quote-argument newfile))
+@end example
+@end defun
+
@node Synchronous Processes
@section Creating a Synchronous Process
@cindex synchronous subprocess
user types another @kbd{C-g}, that kills the subprocess instantly with
@code{SIGKILL} and quits immediately. @xref{Quitting}.
- The synchronous subprocess functions returned @code{nil} in version
-18. Now they return an indication of how the process terminated.
+ The synchronous subprocess functions return an indication of how the
+process terminated.
The output from a synchronous subprocess is generally decoded using a
coding system, much like text read from a file. The input sent to a
subprocess by @code{call-process-region} is encoded using a coding
system, much like text written into a file. @xref{Coding Systems}.
+On Microsoft operating systems, additional variables control
+the conversion for end-of-line (@pxref{MS-DOS Subprocesses}).
@defun call-process program &optional infile destination display &rest args
This function calls @var{program} in a separate process and waits for
standard output stream and the standard error stream of the process.
@item a string
-Find the buffer with that name, then insert the output in that buffer,
-before point.
+Insert the output in a buffer with that name, before point.
@item @code{t}
Insert the output in the current buffer, before point.
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.
+If @var{error-destination} is @code{nil}, that means to discard the
+error output, @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
@end group
@end smallexample
-The @code{insert-directory} function contains a good example of the use
-of @code{call-process}:
+Here is a good example of the use of @code{call-process}, which used to
+be found in the definition of @code{insert-directory}:
@smallexample
@group
-(call-process insert-directory-program nil t nil switches
+(call-process insert-directory-program nil t nil @var{switches}
(if full-directory-p
(concat (file-name-as-directory file) ".")
file))
then returns the command's output as a string.
@end defun
-@node MS-DOS Subprocesses
-@section MS-DOS Subprocesses
-
- On MS-DOS, you must indicate whether the data going to and from
-a synchronous subprocess are text or binary. Text data requires
-translation between the end-of-line convention used within Emacs
-(a single newline character) and the convention used outside Emacs
-(the two-character sequence, @sc{crlf}).
-
- The variable @code{binary-process-input} applies to input sent to the
-subprocess, and @code{binary-process-output} applies to output received
-from it. A non-@code{nil} value means the data is non-text; @code{nil}
-means the data is text, and calls for conversion.
-
-@defvar binary-process-input
-If this variable is @code{nil}, convert newlines to @sc{crlf} sequences in
-the input to a synchronous subprocess.
-@end defvar
-
-@defvar binary-process-output
-If this variable is @code{nil}, convert @sc{crlf} sequences to newlines in
-the output from a synchronous subprocess.
-@end defvar
-
- @xref{Files and MS-DOS}, for related information.
-
@node Asynchronous Processes
@section Creating an Asynchronous Process
@cindex asynchronous subprocess
command name, and @var{command-args} are the arguments for the shell
command. The variable @code{shell-file-name} specifies which shell to
use.
+
+The point of running a program through the shell, rather than directly
+with @code{start-process}, is so that you can employ shell features such
+as wildcards in the arguments. It follows that if you include an
+arbitrary user-specified filename in the command, you should quote it
+with @code{shell-quote-argument} first, so that any special shell
+characters in the file name do @emph{not} have their special shell
+meanings. @xref{Shell Arguments}.
@end defun
@defvar process-connection-type
For a network connection, @code{process-status} returns one of the symbols
@code{open} or @code{closed}. The latter means that the other side
closed the connection, or Emacs did @code{delete-process}.
-
-In Emacs version 18, the status of a network connection was @code{run}
-if open, and @code{exit} if closed.
@end defun
@defun process-exit-status process
@var{process} (@pxref{Coding Systems}). The value has this form:
@example
-(@var{coding-system-for-decoding}
- . @var{coding-system-for-encoding})
+(@var{coding-system-for-decoding} . @var{coding-system-for-encoding})
@end example
@end defun
signal @code{SIGTSTP}. Use @code{continue-process} to resume its
execution.
-On systems with job control, outside of Emacs)\, the ``stop character''
+Outside of Emacs, on systems with job control, the ``stop character''
(usually @kbd{C-z}) normally sends this signal. When
@var{current-group} is non-@code{nil}, you can think of this function as
``typing @kbd{C-z}'' on the terminal Emacs uses to communicate with the
need to use one of the special characters. Here is a list of them:
@need 1200
-@table @kbd
-@item .@: @r{(Period)}
+@table @asis
+@item @samp{.}@: @r{(Period)}
@cindex @samp{.} in regexp
is a special character that matches any single character except a newline.
Using concatenation, we can make regular expressions like @samp{a.b}, which
matches any three-character string that begins with @samp{a} and ends with
@samp{b}.@refill
-@item *
+@item @samp{*}
@cindex @samp{*} in regexp
is not a construct by itself; it is a postfix operator that means to
match the preceding regular expression repetitively as many times as
concluding that none of them can work. To make sure your regular
expressions run fast, check nested repetitions carefully.
-@item +
+@item @samp{+}
@cindex @samp{+} in regexp
is a postfix operator, similar to @samp{*} except that it must match
the preceding expression at least once. So, for example, @samp{ca+r}
matches the strings @samp{car} and @samp{caaaar} but not the string
@samp{cr}, whereas @samp{ca*r} matches all three strings.
-@item ?
+@item @samp{?}
@cindex @samp{?} in regexp
is a postfix operator, similar to @samp{*} except that it must match the
preceding expression either once or not at all. For example,
@samp{ca?r} matches @samp{car} or @samp{cr}; nothing else.
-@item [ @dots{} ]
-@cindex character set (in regexp)
+@item @samp{[ @dots{} ]}
+@cindex character alternative (in regexp)
@cindex @samp{[} in regexp
@cindex @samp{]} in regexp
-is a @dfn{character set}, which begins with @samp{[} and is terminated
-by @samp{]}. In the simplest case, the characters between the two
-brackets are what this set can match.
+is a @dfn{character alternative}, which begins with @samp{[} and is
+terminated by @samp{]}. In the simplest case, the characters between
+the two brackets are what this character alternative can match.
Thus, @samp{[ad]} matches either one @samp{a} or one @samp{d}, and
@samp{[ad]*} matches any string composed of just @samp{a}s and @samp{d}s
(including the empty string), from which it follows that @samp{c[ad]*r}
matches @samp{cr}, @samp{car}, @samp{cdr}, @samp{caddaar}, etc.
-You can also include character ranges in a character set, by writing the
-starting and ending characters with a @samp{-} between them. Thus,
-@samp{[a-z]} matches any lower-case ASCII letter. Ranges may be
+You can also include character ranges in a character alternative, by
+writing the starting and ending characters with a @samp{-} between them.
+Thus, @samp{[a-z]} matches any lower-case ASCII letter. Ranges may be
intermixed freely with individual characters, as in @samp{[a-z$%.]},
which matches any lower case ASCII letter or @samp{$}, @samp{%} or
period.
(@samp{a} with grave accent) is in the Latin-1 character set.
Note that the usual regexp special characters are not special inside a
-character set. A completely different set of special characters exists
-inside character sets: @samp{]}, @samp{-} and @samp{^}.
+character alternative. A completely different set of characters are
+special inside character alternatives: @samp{]}, @samp{-} and @samp{^}.
-To include a @samp{]} in a character set, you must make it the first
-character. For example, @samp{[]a]} matches @samp{]} or @samp{a}. To
-include a @samp{-}, write @samp{-} as the first or last character of the
-set, or put it after a range. Thus, @samp{[]-]} matches both @samp{]}
-and @samp{-}.
+To include a @samp{]} in a character alternative, you must make it the
+first character. For example, @samp{[]a]} matches @samp{]} or @samp{a}.
+To include a @samp{-}, write @samp{-} as the first or last character of
+the character alternative, or put it after a range. Thus, @samp{[]-]}
+matches both @samp{]} and @samp{-}.
-To include @samp{^} in a set, put it anywhere but at the beginning of
-the set.
+To include @samp{^} in a character alternative, put it anywhere but at
+the beginning.
-@item [^ @dots{} ]
+@item @samp{[^ @dots{} ]}
@cindex @samp{^} in regexp
-@samp{[^} begins a @dfn{complemented character set}, which matches any
+@samp{[^} begins a @dfn{complemented character alternative}, which matches any
character except the ones specified. Thus, @samp{[^a-z0-9A-Z]} matches
all characters @emph{except} letters and digits.
-@samp{^} is not special in a character set unless it is the first
+@samp{^} is not special in a character alternative unless it is the first
character. The character following the @samp{^} is treated as if it
were first (in other words, @samp{-} and @samp{]} are not special there).
-A complemented character set can match a newline, unless newline is
+A complemented character alternative can match a newline, unless newline is
mentioned as one of the characters not to match. This is in contrast to
the handling of regexps in programs such as @code{grep}.
-@item ^
+@item @samp{^}
@cindex @samp{^} in regexp
@cindex beginning of line in regexp
is a special character that matches the empty string, but only at the
When matching a string instead of a buffer, @samp{^} matches at the
beginning of the string or after a newline character @samp{\n}.
-@item $
+@item @samp{$}
@cindex @samp{$} in regexp
is similar to @samp{^} but matches only at the end of a line. Thus,
@samp{x+$} matches a string of one @samp{x} or more at the end of a line.
When matching a string instead of a buffer, @samp{$} matches at the end
of the string or before a newline character @samp{\n}.
-@item \
+@item @samp{\}
@cindex @samp{\} in regexp
has two functions: it quotes the special characters (including
@samp{\}), and it introduces additional special constructs.
second character in the sequence is always an ordinary character on
their own. Here is a table of @samp{\} constructs.
-@table @kbd
+@table @samp
@item \|
@cindex @samp{|} in regexp
@cindex regexp alternative
they don't use up any characters---but whether they match depends on the
context.
-@table @kbd
+@table @samp
@item \`
@cindex @samp{\`} in regexp
matches the empty string, but only at the beginning
One use of @code{regexp-quote} is to combine an exact string match with
context described as a regular expression. For example, this searches
-for the string that is the value of @code{string}, surrounded by
+for the string that is the value of @var{string}, surrounded by
whitespace:
@example
@tindex regexp-opt-depth
@defun regexp-opt-depth regexp
This function returns the total number of grouping constructs
-(parenthesised expressions) in @var{regexp}.
+(parenthesized expressions) in @var{regexp}.
@end defun
@node Regexp Example
"[.?!][]\"')@}]*\\($\\| $\\|\t\\| \\)[ \t\n]*"
@end example
- In contrast, if you evaluate the variable @code{sentence-end}, you
+@noindent
+In contrast, if you evaluate the variable @code{sentence-end}, you
will see the following:
@example
@group
sentence-end
-@result{}
-"[.?!][]\"')@}]*\\($\\| $\\| \\| \\)[
+ @result{} "[.?!][]\"')@}]*\\($\\| $\\| \\| \\)[
]*"
@end group
@end example
@table @code
@item [.?!]
-The first part of the pattern is a character set that matches any one of
-three characters: period, question mark, and exclamation mark. The
-match must begin with one of these three characters.
+The first part of the pattern is a character alternative that matches
+any one of three characters: period, question mark, and exclamation
+mark. The match must begin with one of these three characters.
@item []\"')@}]*
The second part of the pattern matches any closing braces and quotation
marks, zero or more of them, that may follow the period, question mark
or exclamation mark. The @code{\"} is Lisp syntax for a double-quote in
a string. The @samp{*} at the end indicates that the immediately
-preceding regular expression (a character set, in this case) may be
+preceding regular expression (a character alternative, in this case) may be
repeated zero or more times.
@item \\($\\|@ $\\|\t\\|@ @ \\)
@cindex regexp searching
@cindex searching for regexp
- In GNU Emacs, you can search for the next match for a regexp either
-incrementally or not. For incremental search commands, see @ref{Regexp
-Search, , Regular Expression Search, emacs, The GNU Emacs Manual}. Here
-we describe only the search functions useful in programs. The principal
-one is @code{re-search-forward}.
+ In GNU Emacs, you can search for the next match for a regular
+expression either incrementally or not. For incremental search
+commands, see @ref{Regexp Search, , Regular Expression Search, emacs,
+The GNU Emacs Manual}. Here we describe only the search functions
+useful in programs. The principal one is @code{re-search-forward}.
These search functions convert the regular expression to multibyte if
the buffer is multibyte; they convert the regular expression to unibyte
beginning to end, and starts at a specified beginning position.
A true mirror-image of @code{re-search-forward} would require a special
-feature for matching regexps from end to beginning. It's not worth the
-trouble of implementing that.
+feature for matching regular expressions from end to beginning. It's
+not worth the trouble of implementing that.
@end deffn
@defun string-match regexp string &optional start
match data around it, to prevent it from being overwritten.
@menu
+* Replacing Match:: Replacing a substring that was matched.
* Simple Match Data:: Accessing single items of match data,
such as where a particular subexpression started.
-* Replacing Match:: Replacing a substring that was matched.
* Entire Match Data:: Accessing the entire match data at once, as a list.
* Saving Match Data:: Saving and restoring the match data.
@end menu
+@node Replacing Match
+@subsection Replacing the Text That Matched
+
+ This function replaces the text matched by the last search with
+@var{replacement}.
+
+@cindex case in replacements
+@defun replace-match replacement &optional fixedcase literal string subexp
+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 you did the last search in a buffer, you should specify @code{nil}
+for @var{string}. Then @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 you did the search in a string, pass the same string as @var{string}.
+Then @code{replace-match} 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
+different case depending upon the capitalization of the text to be
+replaced. If the original text is all upper case, the replacement text
+is converted to upper case. If the first word of the original text is
+capitalized, then the first word of the replacement text is capitalized.
+If the original text contains just one word, and that word is a capital
+letter, @code{replace-match} considers this a capitalized first word
+rather than all upper case.
+
+If @code{case-replace} is @code{nil}, then case conversion is not done,
+regardless of the value of @var{fixed-case}. @xref{Searching and Case}.
+
+If @var{literal} is non-@code{nil}, then @var{replacement} is inserted
+exactly as it is, the only alterations being case changes as needed.
+If it is @code{nil} (the default), then the character @samp{\} is treated
+specially. If a @samp{\} appears in @var{replacement}, then it must be
+part of one of the following sequences:
+
+@table @asis
+@item @samp{\&}
+@cindex @samp{&} in replacement
+@samp{\&} stands for the entire text being replaced.
+
+@item @samp{\@var{n}}
+@cindex @samp{\@var{n}} in replacement
+@samp{\@var{n}}, where @var{n} is a digit, stands for the text that
+matched the @var{n}th subexpression in the original regexp.
+Subexpressions are those expressions grouped inside @samp{\(@dots{}\)}.
+
+@item @samp{\\}
+@cindex @samp{\} in replacement
+@samp{\\} stands for a single @samp{\} in the replacement text.
+@end table
+
+If @var{subexp} is non-@code{nil}, that says to replace just
+subexpression number @var{subexp} of the regexp that was matched, not
+the entire match. For example, after matching @samp{foo \(ba*r\)},
+calling @code{replace-match} with 1 as @var{subexp} means to replace
+just the text that matched @samp{\(ba*r\)}.
+@end defun
+
@node Simple Match Data
@subsection Simple Match Data Access
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,
+argument @var{in-string}. 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
If @var{count} is zero, then the value is the position of the start of
the entire match. Otherwise, @var{count} specifies a subexpression in
-the regular expresion, and the value of the function is the starting
+the regular expression, and the value of the function is the starting
position of the match for that subexpression.
The value is @code{nil} for a subexpression inside a @samp{\|}
(In this case, the index returned is a buffer position; the first
character of the buffer counts as 1.)
-@node Replacing Match
-@subsection Replacing the Text That Matched
-
- This function replaces the text matched by the last search with
-@var{replacement}.
-
-@cindex case in replacements
-@defun replace-match replacement &optional fixedcase literal string subexp
-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 you did the last search in a buffer, you should specify @code{nil}
-for @var{string}. Then @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 you did the search in a string, pass the same string as @var{string}.
-Then @code{replace-match} 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
-different case depending upon the capitalization of the text to be
-replaced. If the original text is all upper case, the replacement text
-is converted to upper case. If the first word of the original text is
-capitalized, then the first word of the replacement text is capitalized.
-If the original text contains just one word, and that word is a capital
-letter, @code{replace-match} considers this a capitalized first word
-rather than all upper case.
-
-If @code{case-replace} is @code{nil}, then case conversion is not done,
-regardless of the value of @var{fixed-case}. @xref{Searching and Case}.
-
-If @var{literal} is non-@code{nil}, then @var{replacement} is inserted
-exactly as it is, the only alterations being case changes as needed.
-If it is @code{nil} (the default), then the character @samp{\} is treated
-specially. If a @samp{\} appears in @var{replacement}, then it must be
-part of one of the following sequences:
-
-@table @asis
-@item @samp{\&}
-@cindex @samp{&} in replacement
-@samp{\&} stands for the entire text being replaced.
-
-@item @samp{\@var{n}}
-@cindex @samp{\@var{n}} in replacement
-@samp{\@var{n}}, where @var{n} is a digit, stands for the text that
-matched the @var{n}th subexpression in the original regexp.
-Subexpressions are those expressions grouped inside @samp{\(@dots{}\)}.
-
-@item @samp{\\}
-@cindex @samp{\} in replacement
-@samp{\\} stands for a single @samp{\} in the replacement text.
-@end table
-
-If @var{subexp} is non-@code{nil}, that says to replace just
-subexpression number @var{subexp} of the regexp that was matched, not
-the entire match. For example, after matching @samp{foo \(ba*r\)},
-calling @code{replace-match} with 1 as @var{subexp} means to replace
-just the text that matched @samp{\(ba*r\)}.
-@end defun
-
@node Entire Match Data
@subsection Accessing the Entire Match Data
All the elements are markers or @code{nil} if matching was done on a
buffer, and all are integers or @code{nil} if matching was done on a
-string with @code{string-match}. (In Emacs 18 and earlier versions,
-markers were used even for matching on a string, except in the case
-of the integer 0.)
+string with @code{string-match}.
As always, there must be no possibility of intervening searches between
the call to a search function and the call to @code{match-data} that is
an error; that sets the match data in a meaningless but harmless way.
@findex store-match-data
-@code{store-match-data} is an alias for @code{set-match-data}.
+@code{store-match-data} is a semi-obsolete alias for @code{set-match-data}.
@end defun
@node Saving Match Data
data around it.
@end defmac
- You can use @code{set-match-data} together with @code{match-data} to
-imitate the effect of the special form @code{save-match-data}. This is
-useful for writing code that can run in Emacs 18. Here is how:
+ You could use @code{set-match-data} together with @code{match-data} to
+imitate the effect of the special form @code{save-match-data}. Here is
+how:
@example
@group
used for certain purposes in editing:
@defvar page-delimiter
-This is the regexp describing line-beginnings that separate pages. The
-default value is @code{"^\014"} (i.e., @code{"^^L"} or @code{"^\C-l"});
-this matches a line that starts with a formfeed character.
+This is the regular expression describing line-beginnings that separate
+pages. The 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
@chapter Sequences, Arrays, and Vectors
@cindex sequence
- Recall that the @dfn{sequence} type is the union of three other Lisp
-types: lists, vectors, and strings. In other words, any list is a
-sequence, any vector is a sequence, and any string is a sequence. The
-common property that all sequences have is that each is an ordered
-collection of elements.
+ Recall that the @dfn{sequence} type is the union of two other Lisp
+types: lists and arrays. In other words, any list is a sequence, and
+any array is a sequence. The common property that all sequences have is
+that each is an ordered collection of elements.
An @dfn{array} is a single primitive object that has a slot for each
-elements. All the elements are accessible in constant time, but the
-length of an existing array cannot be changed. Strings and vectors are
-the two types of arrays.
+of its elements. All the elements are accessible in constant time, but
+the length of an existing array cannot be changed. Strings, vectors,
+char-tables and bool-vectors are the four types of arrays.
A list is a sequence of elements, but it is not a single primitive
object; it is made of cons cells, one cell per element. Finding the
@example
@group
- ___________________________________
- | |
- | Sequence |
- | ______ ______________________ |
- | | | | | |
- | | List | | Array | |
- | | | | ________ _______ | |
- | |______| | | | | | | |
- | | | Vector | | String| | |
- | | |________| |_______| | |
- | |______________________| |
- |___________________________________|
+ _____________________________________________
+ | |
+ | Sequence |
+ | ______ ________________________________ |
+ | | | | | |
+ | | List | | Array | |
+ | | | | ________ ________ | |
+ | |______| | | | | | | |
+ | | | Vector | | String | | |
+ | | |________| |________| | |
+ | | ____________ _____________ | |
+ | | | | | | | |
+ | | | Char-table | | Bool-vector | | |
+ | | |____________| |_____________| | |
+ | |________________________________| |
+ |_____________________________________________|
@end group
@end example
@node Sequence Functions
@section Sequences
- In Emacs Lisp, a @dfn{sequence} is either a list, a vector or a
-string. The common property that all sequences have is that each is an
-ordered collection of elements. This section describes functions that
-accept any kind of sequence.
+ In Emacs Lisp, a @dfn{sequence} is either a list or an array. The
+common property of all sequences is that they are ordered collections of
+elements. This section describes functions that accept any kind of
+sequence.
@defun sequencep object
Returns @code{t} if @var{object} is a list, vector, or
string, @code{nil} otherwise.
@end defun
+@defun length sequence
+@cindex string length
+@cindex list length
+@cindex vector length
+@cindex sequence length
+This function returns the number of elements in @var{sequence}. If
+@var{sequence} is a cons cell that is not a list (because the final
+@sc{cdr} is not @code{nil}), a @code{wrong-type-argument} error is
+signaled.
+
+@xref{List Elements}, for the related function @code{safe-list}.
+
+@example
+@group
+(length '(1 2 3))
+ @result{} 3
+@end group
+@group
+(length ())
+ @result{} 0
+@end group
+@group
+(length "foobar")
+ @result{} 6
+@end group
+@group
+(length [1 2 3])
+ @result{} 3
+@end group
+@group
+(length (make-bool-vector 5 nil))
+ @result{} 5
+@end group
+@end example
+@end defun
+
+@defun elt sequence index
+@cindex elements of sequences
+This function returns the element of @var{sequence} indexed by
+@var{index}. Legitimate values of @var{index} are integers ranging from
+0 up to one less than the length of @var{sequence}. If @var{sequence}
+is a list, then out-of-range values of @var{index} return @code{nil};
+otherwise, they trigger an @code{args-out-of-range} error.
+
+@example
+@group
+(elt [1 2 3 4] 2)
+ @result{} 3
+@end group
+@group
+(elt '(1 2 3 4) 2)
+ @result{} 3
+@end group
+@group
+;; @r{We use @code{string} to show clearly which character @code{elt} returns.}
+(string (elt "1234" 2))
+ @result{} "3"
+@end group
+@group
+(elt [1 2 3 4] 4)
+ @error{}Args out of range: [1 2 3 4], 4
+@end group
+@group
+(elt [1 2 3 4] -1)
+ @error{}Args out of range: [1 2 3 4], -1
+@end group
+@end example
+
+This function generalizes @code{aref} (@pxref{Array Functions}) and
+@code{nth} (@pxref{List Elements}).
+@end defun
+
@defun copy-sequence sequence
@cindex copying sequences
Returns a copy of @var{sequence}. The copy is the same type of object
@end example
@end defun
-@defun length sequence
-@cindex string length
-@cindex list length
-@cindex vector length
-@cindex sequence length
-Returns the number of elements in @var{sequence}. If @var{sequence} is
-a cons cell that is not a list (because the final @sc{cdr} is not
-@code{nil}), a @code{wrong-type-argument} error is signaled.
-
-@xref{List Elements}, for the related function @code{safe-list}.
-
-@example
-@group
-(length '(1 2 3))
- @result{} 3
-@end group
-@group
-(length ())
- @result{} 0
-@end group
-@group
-(length "foobar")
- @result{} 6
-@end group
-@group
-(length [1 2 3])
- @result{} 3
-@end group
-@end example
-@end defun
-
-@defun elt sequence index
-@cindex elements of sequences
-This function returns the element of @var{sequence} indexed by
-@var{index}. Legitimate values of @var{index} are integers ranging from
-0 up to one less than the length of @var{sequence}. If @var{sequence}
-is a list, then out-of-range values of @var{index} return @code{nil};
-otherwise, they trigger an @code{args-out-of-range} error.
-
-@example
-@group
-(elt [1 2 3 4] 2)
- @result{} 3
-@end group
-@group
-(elt '(1 2 3 4) 2)
- @result{} 3
-@end group
-@group
-(char-to-string (elt "1234" 2))
- @result{} "3"
-@end group
-@group
-(elt [1 2 3 4] 4)
- @error{}Args out of range: [1 2 3 4], 4
-@end group
-@group
-(elt [1 2 3 4] -1)
- @error{}Args out of range: [1 2 3 4], -1
-@end group
-@end example
-
-This function generalizes @code{aref} (@pxref{Array Functions}) and
-@code{nth} (@pxref{List Elements}).
-@end defun
-
@node Arrays
@section Arrays
@cindex array
requires access time that is proportional to the position of the element
in the list.
- When you create an array, you must specify how many elements it has.
-The amount of space allocated depends on the number of elements.
-Therefore, it is impossible to change the size of an array once it is
-created; you cannot add or remove elements. However, you can replace an
-element with a different value.
-
- Emacs defines two types of array, both of which are one-dimensional:
-@dfn{strings} and @dfn{vectors}. A vector is a general array; its
-elements can be any Lisp objects. A string is a specialized array; its
-elements must be characters (i.e., integers between 0 and 255). Each
-type of array has its own read syntax. @xref{String Type}, and
-@ref{Vector Type}.
+ Emacs defines four types of array, both of which are one-dimensional:
+@dfn{strings}, @dfn{vectors}, @dfn{bool-vectors} and @dfn{char-tables}.
+A vector is a general array; its elements can be any Lisp objects. A
+string is a specialized array; its elements must be characters (i.e.,
+integers between 0 and 255). Each type of array has its own read
+syntax. @xref{String Type}, and @ref{Vector Type}.
- Both kinds of array share these characteristics:
+ All four kinds of array share these characteristics:
@itemize @bullet
@item
index 1, and so on. This is called @dfn{zero-origin} indexing. For
example, an array of four elements has indices 0, 1, 2, @w{and 3}.
+@item
+The length of the array is fixed once you create it; you cannot
+change the length of an existing array.
+
+@item
+The array is a constant, for evaluation---in other words, it evaluates
+to itself.
+
@item
The elements of an array may be referenced or changed with the functions
@code{aref} and @code{aset}, respectively (@pxref{Array Functions}).
@end itemize
- In principle, if you wish to have an array of text characters, you
-could use either a string or a vector. In practice, we always choose
-strings for such applications, for four reasons:
+ When you create an array, other than a char-table, you must specify
+its length. You cannot specify the length of a char-table, because that
+is determined by the range of character codes.
+
+ In principle, if you want an array of text characters, you could use
+either a string or a vector. In practice, we always choose strings for
+such applications, for four reasons:
@itemize @bullet
@item
@example
@group
(arrayp [a])
-@result{} t
+ @result{} t
(arrayp "asdf")
-@result{} t
+ @result{} t
+(arrayp (syntax-table)) ;; @r{A char-table.}
+ @result{} t
@end group
@end example
@end defun
@result{} [2 3 5 7 11 13]
(aref primes 4)
@result{} 11
-(elt primes 4)
- @result{} 11
@end group
-
@group
(aref "abcdefg" 1)
@result{} 98 ; @r{@samp{b} is @sc{ASCII} code 98.}
Arrays in Lisp, like arrays in most languages, are blocks of memory
whose elements can be accessed in constant time. A @dfn{vector} is a
-general-purpose array; its elements can be any Lisp objects. (By
-contrast, a string can hold only characters as elements.) Vectors in
-Emacs are used for obarrays (vectors of symbols), and as part of keymaps
-(vectors of commands). They are also used internally as part of the
-representation of a byte-compiled function; if you print such a
+general-purpose array of specified length; its elements can be any Lisp
+objects. (By contrast, a string can hold only characters as elements.)
+Vectors in Emacs are used for obarrays (vectors of symbols), and as part
+of keymaps (vectors of commands). They are also used internally as part
+of the representation of a byte-compiled function; if you print such a
function, you will see a vector in it.
In Emacs Lisp, the indices of the elements of a vector start from zero
@end example
@node Vector Functions
-@section Functions That Operate on Vectors
+@section Functions for Vectors
Here are some functions that relate to vectors:
@end group
@end example
+The @code{vconcat} function also allows byte-code function objects as
+arguments. This is a special feature to make it easy to access the entire
+contents of a byte-code function object. @xref{Byte-Code Objects}.
+
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
A char-table is much like a vector, except that it is indexed by
character codes. Any valid character code, without modifiers, can be
-used as an index in a char-table. You can access a char-table with
-@code{aref} and @code{aset}, just like a vector.
+used as an index in a char-table. You can access a char-table's
+elements with @code{aref} and @code{aset}, as with any array.
+Char-tables are constants when evaluated.
@cindex extra slots of char-table
@cindex subtype of char-table
element is initialized to @var{init}, which defaults to @code{nil}. You
cannot alter the subtype of a char-table after the char-table is
created.
+
+There is no argument to specify the length of the char-table, because
+all char-tables have room for any valid character code as an index.
@end defun
@tindex char-table-p
@defun char-table-p object
-This function returns @code{t} if @code{object} is a char-table,
+This function returns @code{t} if @var{object} is a char-table,
otherwise @code{nil}.
@end defun
@var{function} is called with two arguments, a key and a value. The key
is a possible @var{range} argument for @code{char-table-range}, and the
value is @code{(char-table-range @var{char-table} @var{key})}. Invalid
-character codes are never used as the key.
+character codes are never used as @var{key}.
-Overall, the keys-value pairs passed to @var{function} describe all the
+Overall, the key-value pairs passed to @var{function} describe all the
values stored in @var{char-table}.
@end defun
A bool-vector is much like a vector, except that it stores only the
values @code{t} and @code{nil}. If you try to store any non-@code{nil}
-value into an element of the bool-vector, that actually stores @code{t}
-there.
+value into an element of the bool-vector, the effect is to store
+@code{t} there. As with all arrays, bool-vector indices start from 0,
+and the length cannot be changed once the bool-vector is created.
+Bool-vectors are constants when evaluated.
There are two special functions for working with bool-vectors; aside
from that, you manipulate them with same functions used for other kinds
@item @var{function}
@cindex function input stream
-The input characters are generated by @var{function}, one character per
-call. Normally @var{function} is called with no arguments, and should
-return a character.
-
-@cindex unreading
-Occasionally @var{function} is called with one argument (always a
-character). When that happens, @var{function} should save the argument
-and arrange to return it on the next call. This is called
-@dfn{unreading} the character; it happens when the Lisp reader reads one
-character too many and wants to ``put it back where it came from''.
-In this case, it makes no difference what value @var{function} returns.
+The input characters are generated by @var{function}, which must support
+two kinds of calls:
+
+@itemize @bullet
+@item
+When it is called with no arguments, it should return the next character.
+
+@item
+When it is called with one argument (always a character), @var{function}
+should save the argument and arrange to return it on the next call.
+This is called @dfn{unreading} the character; it happens when the Lisp
+reader reads one character too many and wants to ``put it back where it
+came from''. In this case, it makes no difference what value
+@var{function} returns.
+@end itemize
@item @code{t}
@cindex @code{t} input stream
Note that the first read skips a space. Reading skips any amount of
whitespace preceding the significant text.
- In Emacs 18, reading a symbol discarded the delimiter terminating the
-symbol. Thus, point would end up at the beginning of @samp{contents}
-rather than after @samp{the}. The current behavior is superior because
-it correctly handles input such as @samp{bar(foo)}, where the
-open-parenthesis that ends one object is needed as the beginning of
-another object.
-
Here is an example of reading from a stream that is a marker,
initially positioned at the beginning of the buffer shown. The value
read is the symbol @code{This}.
remaining character in the string (i.e., the first one not read).
If @var{start} is supplied, then reading begins at index @var{start} in
-the string (where the first character is at index 0). If @var{end} is
-also supplied, then reading stops just before that index, as if the rest
-of the string were not there.
+the string (where the first character is at index 0). If you specify
+@var{end}, then reading is forced to stop just before that index, as if
+the rest of the string were not there.
For example:
@end table
Many of the valid output streams are also valid as input streams. The
-difference between input and output streams is therefore mostly one of
-how you use a Lisp object, not a distinction of types of object.
+difference between input and output streams is therefore more a matter
+of how you use a Lisp object, than of different types of object.
Here is an example of a buffer used as an output stream. Point is
initially located as shown immediately before the @samp{h} in
for full details. You specify quoting or no quoting by the choice of
printing function.
- If the text is to be read back into Lisp, then it is best to print
-with quoting characters to avoid ambiguity. Likewise, if the purpose is
-to describe a Lisp object clearly for a Lisp programmer. However, if
-the purpose of the output is to look nice for humans, then it is better
-to print without quoting.
+ If the text is to be read back into Lisp, then you should print with
+quoting characters to avoid ambiguity. Likewise, if the purpose is to
+describe a Lisp object clearly for a Lisp programmer. However, if the
+purpose of the output is to look nice for humans, then it is usually
+better to print without quoting.
- Printing a self-referent Lisp object requires an infinite amount of
-text. In certain cases, trying to produce this text leads to a stack
-overflow. Emacs detects such recursion and prints @samp{#@var{level}}
-instead of recursively printing an object already being printed. For
-example, here @samp{#0} indicates a recursive reference to the object at
-level 0 of the current print operation:
+ Printing a self-referent Lisp object in the normal way would require
+an infinite amount of text, and could even result in stack overflow.
+Emacs detects such recursion and prints @samp{#@var{level}} instead of
+recursively printing an object already being printed. For example, here
+@samp{#0} indicates a recursive reference to the object at level 0 of
+the current print operation:
@example
(setq foo (list nil))
are printed as @samp{\n} and formfeeds are printed as @samp{\f}.
Normally these characters are printed as actual newlines and formfeeds.
-This variable affects the print functions @code{prin1} and @code{print},
-as well as everything that uses them. It does not affect @code{princ}.
-Here is an example using @code{prin1}:
+This variable affects the print functions @code{prin1} and @code{print}
+that print with quoting. It does not affect @code{princ}. Here is an
+example using @code{prin1}:
@example
@group
* Text Comparison:: Comparing characters or strings.
* String Conversion:: Converting characters or strings and vice versa.
* Formatting Strings:: @code{format}: Emacs's analog of @code{printf}.
-* Character Case:: Case conversion functions.
-* Case Table:: Customizing case conversion.
+* Case Conversion:: Case conversion functions.
+* Case Tables:: Customizing case conversion.
@end menu
@node String Basics
Strings in Emacs Lisp are arrays that contain an ordered sequence of
characters. Characters are represented in Emacs Lisp as integers;
-whether an integer was intended as a character or not is determined only
-by how it is used. Thus, strings really contain integers.
+whether an integer is a character or not is determined only by how it is
+used. Thus, strings really contain integers.
The length of a string (like any array) is fixed, and cannot be
altered once the string exists. Strings in Lisp are @emph{not}
terminated by a distinguished character code. (By contrast, strings in
C are terminated by a character with @sc{ASCII} code 0.)
- Since strings are considered arrays, you can operate on them with the
-general array functions. (@xref{Sequences Arrays Vectors}.) For
-example, you can access or change individual characters in a string
-using the functions @code{aref} and @code{aset} (@pxref{Array
-Functions}).
+ Since strings are arrays, and therefore sequences as well, you can
+operate on them with the general array and sequence functions.
+(@xref{Sequences Arrays Vectors}.) For example, you can access or
+change individual characters in a string using the functions @code{aref}
+and @code{aset} (@pxref{Array Functions}).
There are two text representations for non-@sc{ASCII} characters in
Emacs strings (and in buffers): unibyte and multibyte (@pxref{Text
Sometimes key sequences are represented as strings. When a string is
a key sequence, string elements in the range 128 to 255 represent meta
-characters (which are extremely large integers) rather than keyboard
-events in the range 128 to 255.
+characters (which are extremely large integers) rather than character
+codes in the range 128 to 255.
Strings cannot hold characters that have the hyper, super or alt
modifiers; they can hold @sc{ASCII} control characters, but no other
If the characters copied from @var{string} have text properties, the
properties are copied into the new string also. @xref{Text Properties}.
+@code{substring} also allows vectors for the first argument.
+For example:
+
+@example
+(substring [a b (c) "d"] 1 3)
+ @result{} [b (c)]
+@end example
+
A @code{wrong-type-argument} error is signaled if either @var{start} or
@var{end} is not an integer or @code{nil}. An @code{args-out-of-range}
error is signaled if @var{start} indicates a character following
@var{end}, or if either integer is out of range for @var{string}.
-@code{substring} actually allows vectors as well as strings for
-the first argument.
-
Contrast this function with @code{buffer-substring} (@pxref{Buffer
Contents}), which returns a string containing a portion of the text in
the current buffer. The beginning of a string is at index 0, but the
@var{idx} @var{char})} stores @var{char} into @var{string} at index
@var{idx}. Each character occupies one or more bytes, and if @var{char}
needs a different number of bytes from the character already present at
-that index, @code{aset} gets an error.
+that index, @code{aset} signals an error.
A more powerful function is @code{store-substring}:
Since it is impossible to change the length of an existing string, it is
an error if @var{obj} doesn't fit within @var{string}'s actual length,
-or if it requires a different number of bytes from the characters
-currently present at that point in @var{string}.
+of if any new character requires a different number of bytes from the
+character currently present at that point in @var{string}.
@end defun
@need 2000
strings. When @code{equal} (@pxref{Equality Predicates}) compares two
strings, it uses @code{string=}.
-If the arguments contain non-@sc{ASCII} characters, and one is unibyte
+If the strings contain non-@sc{ASCII} characters, and one is unibyte
while the other is multibyte, then they cannot be equal. @xref{Text
Representations}.
@end defun
@var{string2}, then @var{string1} is greater, and this function returns
@code{nil}. If the two strings match entirely, the value is @code{nil}.
-Pairs of characters are compared by their @sc{ASCII} codes. Keep in
-mind that lower case letters have higher numeric values in the
-@sc{ASCII} character set than their upper case counterparts; numbers and
+Pairs of characters are compared according to their character codes.
+Keep in mind that lower case letters have higher numeric values in the
+@sc{ASCII} character set than their upper case counterparts; digits and
many punctuation characters have a lower numeric value than upper case
-letters. A unibyte non-@sc{ASCII} character is always less than any
+letters. An @sc{ASCII} character is less than any non-@sc{ASCII}
+character; a unibyte non-@sc{ASCII} character is always less than any
multibyte non-@sc{ASCII} character (@pxref{Text Representations}).
@example
@defun char-to-string character
@cindex character to string
- This function returns a new string with a length of one character.
-The value of @var{character}, modulo 256, is used to initialize the
-element of the string.
-
-This function is similar to @code{make-string} with an integer argument
-of 1. (@xref{Creating Strings}.) This conversion can also be done with
-@code{format} using the @samp{%c} format specification.
-(@xref{Formatting Strings}.)
-
-@example
-(char-to-string ?x)
- @result{} "x"
-(char-to-string (+ 256 ?x))
- @result{} "x"
-(make-string 1 ?x)
- @result{} "x"
-@end example
+This function returns a new string containing one character,
+@var{character}. This function is semi-obsolete because the function
+@code{string} is more general. @xref{Creating Strings}.
@end defun
@defun string-to-char string
in how they use the result of formatting.
@defun format string &rest objects
- This function returns a new string that is made by copying
+This function returns a new string that is made by copying
@var{string} and then replacing any format specification
in the copy with encodings of the corresponding @var{objects}. The
arguments @var{objects} are the computed values to be formatted.
@item %s
Replace the specification with the printed representation of the object,
made without quoting (that is, using @code{princ}, not
-@code{print}---@pxref{Output Functions}). Thus, strings are represented
+@code{prin1}---@pxref{Output Functions}). Thus, strings are represented
by their contents alone, with no @samp{"} characters, and symbols appear
without @samp{\} characters.
@end group
@end smallexample
-@node Character Case
+@node Case Conversion
@comment node-name, next, previous, up
-@section Character Case
+@section Case Conversion in Lisp
@cindex upper case
@cindex lower case
@cindex character case
+@cindex case conversion in Lisp
The character case functions change the case of single characters or
of the contents of strings. The functions convert only alphabetic
@end example
@end defun
-@node Case Table
+@defun upcase-initials string
+This function capitalizes the initials of the words in @var{string}.
+without altering any letters other than the initials. It returns a new
+string whose contents are a copy of @var{string-or-char}, in which each
+word has been converted to upper case.
+
+The definition of a word is any sequence of consecutive characters that
+are assigned to the word constituent syntax class in the current syntax
+table (@xref{Syntax Class Table}).
+
+@example
+@group
+(upcase-initials "The CAT in the hAt")
+ @result{} "The CAT In The HAt"
+@end group
+@end example
+@end defun
+
+@node Case Tables
@section The Case Table
You can customize case conversion by installing a special @dfn{case
table}. A case table specifies the mapping between upper case and lower
-case letters. It affects both the string and character case conversion
-functions (see the previous section) and those that apply to text in the
-buffer (@pxref{Case Changes}).
+case letters. It affects both the case conversion functions for Lisp
+objects (see the previous section) and those that apply to text in the
+buffer (@pxref{Case Changes}). Each buffer has a case table; there is
+also a standard case table which is used to initialize the case table
+of new buffers.
- A case table is a char-table whose subtype is @code{case-table}. This
-char-table maps each character into the corresponding lower case
-character It has three extra slots, which are related tables:
+ A case table is a char-table (@pxref{Char-Tables}) whose subtype is
+@code{case-table}. This char-table maps each character into the
+corresponding lower case character. It has three extra slots, which
+hold related tables:
@table @var
@item upcase
equivalent characters.)
When you construct a case table, you can provide @code{nil} for
-@var{canonicalize}; then Emacs fills in this string from the lower case
+@var{canonicalize}; then Emacs fills in this slot from the lower case
and upper case mappings. You can also provide @code{nil} for
-@var{equivalences}; then Emacs fills in this string from
+@var{equivalences}; then Emacs fills in this slot from
@var{canonicalize}. In a case table that is actually in use, those
components are non-@code{nil}. Do not try to specify @var{equivalences}
without also specifying @var{canonicalize}.
- Each buffer has a case table. Emacs also has a @dfn{standard case
-table} which is copied into each buffer when you create the buffer.
-Changing the standard case table doesn't affect any existing buffers.
-
Here are the functions for working with case tables:
@defun case-table-p object
@defun set-standard-case-table table
This function makes @var{table} the standard case table, so that it will
-apply to any buffers created subsequently.
+be used in any buffers created subsequently.
@end defun
@defun standard-case-table
The following three functions are convenient subroutines for packages
that define non-@sc{ASCII} character sets. They modify the specified
case table @var{case-table}; they also modify the standard syntax table.
-@xref{Syntax Tables}.
+@xref{Syntax Tables}. Normally you would use these functions to change
+the standard case table.
@defun set-case-syntax-pair uc lc case-table
This function specifies a pair of corresponding letters, one upper case
@code{defvar} and @code{defconst} are special forms that define a
symbol as a global variable. They are documented in detail in
-@ref{Defining Variables}.
+@ref{Defining Variables}. For defining user option variables that can
+be customized, use @code{defcustom} (@pxref{Customization}).
@code{defun} defines a symbol as a function, creating a lambda
expression and storing it in the function cell of the symbol. This
to result in good hashing; lengths one less than a power of two are also
good.
- It is possible for two different symbols to have the same name in
-different obarrays; these symbols are not @code{eq} or @code{equal}.
-However, this normally happens only as part of the abbrev mechanism
-(@pxref{Abbrevs}).
-
@strong{Do not try to put symbols in an obarray yourself.} This does
not work---only @code{intern} can enter a symbol in an obarray properly.
symbol are stored in the same property list, so there is a possibility
of a conflict between different uses of a property name. (For this
reason, it is a good idea to choose property names that are probably
-unique, such as by including the name of the library in the property
-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.
+unique, such as by beginning the property name with the program's usual
+name-prefix for variables and functions.) 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
@end example
@end defun
+ You could define @code{put} in terms of @code{plist-put} as follows:
+
+@example
+(defun put (symbol prop value)
+ (setplist symbol
+ (plist-put (symbol-plist symbol) prop value)))
+@end example
this chapter.
@end ifinfo
- A syntax table is a char-table (@pxref{Char-Tables}). Each element is
-a list that encodes the syntax of the character in question.
+ A syntax table is a char-table (@pxref{Char-Tables}). The element at
+index @var{c} describes the character with code @var{c}. The element's
+value should be a list that encodes the syntax of the character in
+question.
Syntax tables are used only for moving across text, not for the Emacs
Lisp reader. Emacs Lisp uses built-in syntactic rules when reading Lisp
-expressions, and these rules cannot be changed.
+expressions, and these rules cannot be changed. (Some Lisp systems
+provide ways to redefine the read syntax, but we decided to leave this
+feature out of Emacs Lisp for simplicity.)
Each buffer has its own major mode, and each major mode has its own
idea of the syntactic class of various characters. For example, in Lisp
This section describes the syntax classes and flags that denote the
syntax of a character, and how they are represented as a @dfn{syntax
descriptor}, which is a Lisp string that you pass to
-@code{modify-syntax-entry} to specify the desired syntax.
+@code{modify-syntax-entry} to specify the syntax you want.
- Emacs defines a number of @dfn{syntax classes}. Each syntax table
-puts each character into one class. There is no necessary relationship
-between the class of a character in one syntax table and its class in
-any other table.
+ The syntax table specifies a syntax class for each character. There
+is no necessary relationship between the class of a character in one
+syntax table and its class in any other table.
Each class is designated by a mnemonic character, which serves as the
name of the class when you need to specify a class. Usually the
separate symbols and words from each other. Typically, whitespace
characters have no other syntactic significance, and multiple whitespace
characters are syntactically equivalent to a single one. Space, tab,
-newline and formfeed are almost always classified as whitespace.
+newline and formfeed are classified as whitespace in almost all major
+modes.
@end deffn
@deffn {Syntax class} @w{word constituent}
altering syntax tables.
@defun make-syntax-table
-This function creates a new syntax table. Character codes 32 through
-127 are set up by copying the syntax from the standard syntax table.
-All other codes are set up to inherit from the standard syntax table.
+This function creates a new syntax table. It inherits the syntax for
+letters and control characters from the standard syntax table. For
+other characters, the syntax is copied from the standard syntax table.
Most major mode syntax tables are created in this way.
@end defun
@example
@group
-(char-to-string (char-syntax ?\ ))
+(string (char-syntax ?\ ))
@result{} " "
@end group
@group
-(char-to-string (char-syntax ?/))
+(string (char-syntax ?/))
@result{} "."
@end group
@group
-(char-to-string (char-syntax ?\())
+(string (char-syntax ?\())
@result{} "("
@end group
@end example
+
+We use @code{string} to make it easier to see the character returned by
+@code{char-syntax}.
@end defun
@defun set-syntax-table table
the syntax table for specific character occurrences in the buffer.
@xref{Text Properties}.
-The valid values of @code{syntax-table} text property are
+The valid values of @code{syntax-table} text property are:
@table @asis
@item @var{syntax-table}
@node Motion and Syntax
@section Motion and Syntax
- This section describes functions for moving across characters in
-certain syntax classes. None of these functions exists in Emacs
-version 18 or earlier.
+ This section describes functions for moving across characters that
+have certain syntax classes.
@defun skip-syntax-forward syntaxes &optional limit
This function moves point forward across characters having syntax classes
@cindex parse state
The fifth argument @var{state} is a nine-element list of the same form
-as the value of this function, described below. (It is ok to omit the
+as the value of this function, described below. (It is OK to omit the
last element of the nine.) The return value of one call may be used to
initialize the state of the parse on another call to
@code{parse-partial-sexp}.
This table gives the value of @var{syntax-code} which corresponds
to each syntactic type.
-@table @asis
-@item @i{Integer}
-@i{Class}
-@item 0
-whitespace
-@item 1
-punctuation
-@item 2
-word
-@item 3
-symbol
-@item 4
-open parenthesis
-@item 5
-close parenthesis
-@item 6
-expression prefix
-@item 7
-string quote
-@item 8
-paired delimiter
-@item 9
-escape
-@item 10
-character quote
-@item 11
-comment-start
-@item 12
-comment-end
-@item 13
-inherit
-@item 14
-comment-fence
-@item 15
-string-fence
-@end table
+@multitable @columnfractions .05 .3 .3 .3
+@item@tab
+@i{Integer} @i{Class}
+@tab
+@i{Integer} @i{Class}
+@tab
+@i{Integer} @i{Class}
+@item@tab
+0 @ @ whitespace
+@tab
+5 @ @ close parenthesis
+@tab
+10 @ @ character quote
+@item@tab
+1 @ @ punctuation
+@tab
+6 @ @ expression prefix
+@tab
+11 @ @ comment-start
+@item@tab
+2 @ @ word
+@tab
+7 @ @ string quote
+@tab
+12 @ @ comment-end
+@item@tab
+3 @ @ symbol
+@tab
+8 @ @ paired delimiter
+@tab
+13 @ @ inherit
+@item@tab
+4 @ @ open parenthesis
+@tab
+9 @ @ escape
+@tab
+14 @ @ comment-fence
+@item@tab
+15 @ string-fence
+@end multitable
For example, the usual syntax value for @samp{(} is @code{(4 . 41)}.
(41 is the character code for @samp{)}.)
least significant bit. This table gives the power of two which
corresponds to each syntax flag.
-@table @samp
-@item @i{Flag}
-@i{Bit value}
-@item 1
-@code{(lsh 1 16)}
-@item 2
-@code{(lsh 1 17)}
-@item 3
-@code{(lsh 1 18)}
-@item 4
-@code{(lsh 1 19)}
-@item p
-@code{(lsh 1 20)}
-@item b
-@code{(lsh 1 21)}
-@end table
+@multitable @columnfractions .05 .3 .3 .3
+@item@tab
+@i{Prefix} @i{Flag}
+@tab
+@i{Prefix} @i{Flag}
+@tab
+@i{Prefix} @i{Flag}
+@item@tab
+@samp{1} @ @ @code{(lsh 1 16)}
+@tab
+@samp{3} @ @ @code{(lsh 1 18)}
+@tab
+@samp{p} @ @ @code{(lsh 1 20)}
+@item@tab
+@samp{2} @ @ @code{(lsh 1 17)}
+@tab
+@samp{4} @ @ @code{(lsh 1 19)}
+@tab
+@samp{b} @ @ @code{(lsh 1 21)}
+@end multitable
@node Categories
@section Categories
@cindex categories of characters
@dfn{Categories} provide an alternate way of classifying characters
-syntactically. You can define a large number of categories, and then
-independently assign each character to one or more of them. Unlike
+syntactically. You can define several categories as needed, then
+independently assign each character to one or more categories. Unlike
syntax classes, categories are not mutually exclusive; it is normal for
one character to belong to several categories.
Each buffer has a @dfn{category table} which records which categories
are defined and also which characters belong to each category. Each
-category table defines its own categories. Each category has a name,
-which is an @sc{ASCII} printing character in the range @w{@samp{ }} to
-@samp{~}. You specify the name of a category when you define it with
-@code{define-category}.
+category table defines its own categories, but normally these are
+initialized by copying from the standard categories table, so that the
+standard categories are available in all modes.
+
+ Each category has a name, which is an @sc{ASCII} printing character in
+the range @w{@samp{ }} to @samp{~}. You specify the name of a category
+when you define it with @code{define-category}.
The category table is actually a char-table (@pxref{Char-Tables}).
The element of the category table at index @var{c} is a @dfn{category
@defun get-unused-category table
This function returns a category name (a character) which is not
-currently defined in @var{table}. If none is still available, it
-returns @code{nil},
+currently defined in @var{table}. If all possible categories are in use
+in @var{table}, it returns @code{nil},
@end defun
@defun category-table
@end example
@end defun
+@defun char-before position
+This function returns the character in the current buffer immediately
+before position @var{position}. If @var{position} is out of range for
+this purpose, either before the beginning of the buffer, or at or beyond
+the end, then the value is @code{nil}.
+@end defun
+
@defun following-char
This function returns the character following point in the current
buffer. This is similar to @code{(char-after (point))}. However, if
@defun buffer-substring-no-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-no-properties 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
@cindex insertion of text
@cindex text insertion
+@cindex insertion before point
+@cindex before point, insertion
@dfn{Insertion} means adding new text to a buffer. The inserted text
goes at point---between the character before point and the character
-after point.
+after point. Some insertion functions leave point before the inserted
+text, while other functions leave it after. We call the former
+insertion @dfn{after point} and the latter insertion @dfn{before point}.
Insertion relocates markers that point at positions after the
insertion point, so that they stay with the surrounding text
(@pxref{Markers}). When a marker points at the place of insertion,
-insertion normally doesn't relocate the marker, so that it points to the
-beginning of the inserted text; however, certain special functions such
-as @code{insert-before-markers} relocate such markers to point after the
-inserted text.
-
-@cindex insertion before point
-@cindex before point, insertion
- Some insertion functions leave point before the inserted text, while
-other functions leave it after. We call the former insertion @dfn{after
-point} and the latter insertion @dfn{before point}.
+insertion may or may not relocate the marker, depending on the marker's
+insertion type (@pxref{Marker Insertion Types}). Certain special
+functions such as @code{insert-before-markers} relocate all such markers
+to point after the inserted text, regardless of the markers' insertion
+type.
Insertion functions signal an error if the current buffer is
read-only.
the insertion point, the inserted text falls inside that overlay.
@end defun
-@defun insert-char character count &optional inherit
+@defun insert-char character &optional count inherit
This function inserts @var{count} instances of @var{character} into the
-current buffer before point. The argument @var{count} must be a number,
-and @var{character} must be a character. The value is @code{nil}.
-@c It's unfortunate that count comes second. Not like make-string, etc.
+current buffer before point. The argument @var{count} should be a
+number (@code{nil} means 1), and @var{character} must be a character.
+The value is @code{nil}.
If @var{inherit} is non-@code{nil}, then the inserted characters inherit
sticky text properties from the two characters before and after the
The value returned is always @code{nil}.
@end deffn
+@tindex backward-delete-char-untabify-method
+@defopt backward-delete-char-untabify-method
+This option specifies how @code{backward-delete-char-untabify} should
+deal with whitespace. Possible values include @code{untabify}, the
+default, meaning convert a tab to many spaces and delete one;
+@code{hungry}, meaning delete all the whitespace characters before point
+with one command, and @code{nil}, meaning do nothing special for
+whitespace characters.
+@end defopt
+
@node User-Level Deletion
@section User-Level Deletion Commands
@section The Kill Ring
@cindex kill ring
- @dfn{Kill} functions delete text like the deletion functions, but save
+ @dfn{Kill functions} delete text like the deletion functions, but save
it so that the user can reinsert it by @dfn{yanking}. Most of these
functions have @samp{kill-} in their name. By contrast, the functions
whose names start with @samp{delete-} normally do not save text for
@node Low-Level Kill Ring
@subsection Low-Level Kill Ring
- These functions and variables provide access to the kill ring at a lower
-level, but still convenient for use in Lisp programs. They take care of
-interaction with X Window selections. They do not exist in Emacs
-version 18.
+ These functions and variables provide access to the kill ring at a
+lower level, but still convenient for use in Lisp programs, because they
+take care of interaction with window system selections
+(@pxref{Window System Selections}).
@defun current-kill n &optional do-not-move
The function @code{current-kill} rotates the yanking pointer which
then that value is used as the ``most recent kill''. If it returns
@code{nil}, then the first element of @code{kill-ring} is used.
-The normal use of this hook is to get the X server's primary selection
-as the most recent kill, even if the selection belongs to another X
-client. @xref{X Selections}.
+The normal use of this hook is to get the window system's primary
+selection as the most recent kill, even if the selection belongs to
+another application. @xref{Window System Selections}.
@end defvar
@defvar interprogram-cut-function
If the value is a function, @code{kill-new} and @code{kill-append} call
it with the new first element of the kill ring as an argument.
-The normal use of this hook is to set the X server's primary selection
-from the newly killed text.
+The normal use of this hook is to set the window system's primary
+selection from the newly killed text. @xref{Window System Selections}.
@end defvar
@node Internals of Kill Ring
@example
@group
-kill-ring kill-ring-yank-pointer
- | |
- | ___ ___ ---> ___ ___ ___ ___
- --> |___|___|------> |___|___|--> |___|___|--> nil
+kill-ring ---- kill-ring-yank-pointer
+ | |
+ | v
+ | --- --- --- --- --- ---
+ --> | | |------> | | |--> | | |--> nil
+ --- --- --- --- --- ---
| | |
| | |
| | -->"yet older text"
This function returns @code{nil}. It cannot be called interactively.
The name @code{buffer-flush-undo} is not considered obsolete, but the
-preferred name @code{buffer-disable-undo} is new as of Emacs versions
-19.
+preferred name is @code{buffer-disable-undo}.
@end defun
As editing continues, undo lists get longer and longer. To prevent
can be @code{left}, @code{right}, @code{full}, or @code{center}, to
request a specific style of justification. If it is @code{t}, that
means to use the current justification style for this part of the text
-(see @code{current-justification}, below).
+(see @code{current-justification}, below). Any other value is treated
+as @code{full}.
When you call the filling functions interactively, using a prefix
argument implies the value @code{full} for @var{justify}.
@defvar left-margin
This variable specifies the base left margin column. In Fundamental
-mode, @key{LFD} indents to this column. This variable automatically
+mode, @kbd{C-j} indents to this column. This variable automatically
becomes buffer-local when set in any fashion.
@end defvar
+@tindex fill-nobreak-predicate
+@defvar fill-nobreak-predicate
+This variable gives major modes a way to specify not to break a line at
+certain places. Its value should be a function. This function is
+called during filling, with no arguments and with point located at the
+place where a break is being considered. If the function returns
+non-@code{nil}, then the line won't be broken there.
+@end defvar
+
@node Auto Filling
@comment node-name, next, previous, up
@section Auto Filling
@defvar normal-auto-fill-function
This variable specifies the function to use for
@code{auto-fill-function}, if and when Auto Fill is turned on. Major
-modes can set this locally to alter how Auto Fill works.
+modes can set buffer-local values for this variable to alter how Auto
+Fill works.
@end defvar
@node Sorting
(save-restriction
(narrow-to-region beg end)
(goto-char (point-min))
- (sort-subr reverse
- 'forward-line
- 'end-of-line)))
+ (sort-subr reverse 'forward-line 'end-of-line)))
@end group
@end example
@group
(sort-subr reverse
(function
- (lambda ()
- (skip-chars-forward "\n \t\f")))
+ (lambda () (skip-chars-forward "\n \t\f")))
'forward-paragraph)
@end group
@end example
Note that @code{sort-columns} uses the @code{sort} utility program,
and so cannot work properly on text containing tab characters. Use
-@kbd{M-x @code{untabify}} to convert tabs to spaces before sorting.
+@kbd{M-x untabify} to convert tabs to spaces before sorting.
@end deffn
@node Columns
This section describes the primitive functions used to count and
insert indentation. The functions in the following sections use these
-primitives.
+primitives. @xref{Width}, for related functions.
@defun current-indentation
@comment !!Type Primitive Function
@comment !!SourceFile indent.c
If this variable is non-@code{nil}, indentation functions can insert
tabs as well as spaces. Otherwise, they insert only spaces. Setting
-this variable automatically makes it local to the current buffer.
+this variable automatically makes it buffer-local in the current buffer.
@end defopt
@node Mode-Specific Indent
@node Case Changes
@comment node-name, next, previous, up
@section Case Changes
-@cindex case changes
+@cindex case conversion in buffers
The case change commands described here work on text in the current
-buffer. @xref{Character Case}, for case conversion commands that work
-on strings and characters. @xref{Case Table}, for how to customize
+buffer. @xref{Case Conversion}, for case conversion functions that work
+on strings and characters. @xref{Case Tables}, for how to customize
which characters are upper or lower case and how to convert them.
@deffn Command capitalize-region start end
@subsection Properties with Special Meanings
Here is a table of text property names that have special built-in
-meanings. The following section lists a few more special property names
-that are used to control filling. All other names have no standard
-meaning, and you can use them as you like.
+meanings. The following sections list a few additional special property
+names that control filling and property inheritance. All other names
+have no standard meaning, and you can use them as you like.
@table @code
@cindex category of text character
(save-excursion
(set-buffer (window-buffer (posn-window (event-end event))))
(save-excursion
- (goto-char (posn-point (event-end event)))
- (setq file (dired-get-filename))))
+ (goto-char (posn-point (event-end event)))
+ (setq file (dired-get-filename))))
(select-window (posn-window (event-end event)))
(find-file-other-window (file-name-sans-versions file t))))
@end smallexample
@cindex registers
A register is a sort of variable used in Emacs editing that can hold a
-marker, a string, a rectangle, a window configuration (of one frame), or
-a frame configuration (of all frames). Each register is named by a
-single character. All characters, including control and meta characters
-(but with the exception of @kbd{C-g}), can be used to name registers.
-Thus, there are 255 possible registers. A register is designated in
-Emacs Lisp by a character that is its name.
-
- The functions in this section return unpredictable values unless
-otherwise stated.
+variety of different kinds of values. Each register is named by a
+single character. All ASCII characters and their meta variants (but
+with the exception of @kbd{C-g}) can be used to name registers. Thus,
+there are 255 possible registers. A register is designated in Emacs
+Lisp by the character that is its name.
@defvar register-alist
This variable is an alist of elements of the form @code{(@var{name} .
register that has been used.
The object @var{name} is a character (an integer) identifying the
-register. The object @var{contents} is a string, marker, window
-configuration, frame configuration, or list representing the register
-contents. A string represents text stored in the register. A marker
-represents a position. A list represents a rectangle; its elements are
-strings, one per line of the rectangle.
+register.
@end defvar
+ The @var{contents} of a register can have several possible types:
+
+@table @asis
+@item a number
+A number stands for itself. If @code{insert-register} finds a number
+in the register, it converts the number to decimal.
+
+@item a marker
+A marker represents a buffer position to jump to.
+
+@item a string
+A string is text saved in the register.
+
+@item a rectangle
+A rectangle is represented by a list of strings.
+
+@item @code{(@var{window-configuration} @var{position})}
+This represents a window configuration to restore in one frame, and a
+position to jump to in the current buffer.
+
+@item @code{(@var{frame-configuration} @var{position})}
+This represents a frame configuration to restore, and a position
+to jump to in the current buffer.
+
+@item (file @var{filename})
+This represents a file to visit; jumping to this value visits file
+@var{filename}.
+
+@item (file-query @var{filename} @var{position})
+This represents a file to visit and a position in it; jumping to this
+value visits file @var{filename} and goes to buffer position
+@var{position}. Restoring this type of position asks the user for
+confirmation first.
+@end table
+
+ The functions in this section return unpredictable values unless
+otherwise stated.
+
@defun get-register reg
This function returns the contents of the register
@var{reg}, or @code{nil} if it has no contents.
If a program makes several text changes in the same area of the buffer,
using the macro @code{combine-after-change-calls} around that part of
the program can make it run considerably faster when after-change hooks
-are in use.
+are in use. When the after-change hooks are ultimately called, the
+arguments specify a portion of the buffer including all of the changes
+made within the @code{combine-after-change-calls} body.
@strong{Warning:} You must not alter the values of
@code{after-change-functions} and @code{after-change-function} within
the body of a @code{combine-after-change-calls} form.
+
+@strong{Note:} If the changes you combine occur in widely scattered
+parts of the buffer, this will still work, but it is not advisable,
+because it may lead to inefficient behavior for some change hook
+functions.
@end defmac
@defvar before-change-function
(while list
(funcall (car list) beg end len)
(setq list (cdr list)))))
+
+@group
(add-hooks 'after-change-functions
'indirect-after-change-function)
+@end group
@end example
@defvar first-change-hook
@c Copyright (C) 1990, 1991, 1992, 1993, 1995, 1998 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/tips
-@node Tips, GNU Emacs Internals, Calendar, Top
+@node Tips, GNU Emacs Internals, System Interface, Top
@appendix Tips and Conventions
@cindex tips
@cindex standards of coding style
prefix. This helps avoid name conflicts.
This recommendation applies even to names for traditional Lisp
-primitives that are not primitives in Emacs Lisp---even to @code{cadr}.
-Believe it or not, there is more than one plausible way to define
-@code{cadr}. Play it safe; append your name prefix to produce a name
-like @code{foo-cadr} or @code{mylib-cadr} instead.
+primitives that are not primitives in Emacs Lisp---even to
+@code{copy-list}. Believe it or not, there is more than one plausible
+way to define @code{copy-list}. Play it safe; append your name prefix
+to produce a name like @code{foo-copy-list} or @code{mylib-copy-list}
+instead.
If you write a function that you think ought to be added to Emacs under
a certain name, such as @code{twiddle-files}, don't call it by that name
@end example
@noindent
-(And @var{bar} should contain @code{(provide '@var{bar})}, to make the
-@code{require} work.) This will cause @var{bar} to be loaded when you
-byte-compile @var{foo}. Otherwise, you risk compiling @var{foo} without
-the necessary macro loaded, and that would produce compiled code that
-won't work right. @xref{Compiling Macros}.
+(And the library @var{bar} should contain @code{(provide '@var{bar})},
+to make the @code{require} work.) This will cause @var{bar} to be
+loaded when you byte-compile @var{foo}. Otherwise, you risk compiling
+@var{foo} without the necessary macro loaded, and that would produce
+compiled code that won't work right. @xref{Compiling Macros}.
Using @code{eval-when-compile} avoids loading @var{bar} when
the compiled version of @var{foo} is @emph{used}.
character, a digit, or certain punctuation characters. These sequences
are reserved for major modes.
-Changing all the major modes in Emacs 18 so they would follow this
-convention was a lot of work. Abandoning this convention would make
-that work go to waste, and inconvenience users.
+Changing all the Emacs major modes to follow this convention was a lot
+of work. Abandoning this convention would make that work go to waste,
+and inconvenience users.
@item
Sequences consisting of @kbd{C-c} followed by @kbd{@{}, @kbd{@}},
@item
Do not bind a key sequence ending in @key{ESC} except following
-another @key{ESC}. (That is, it is ok to bind a sequence ending in
+another @key{ESC}. (That is, it is OK to bind a sequence ending in
@kbd{@key{ESC} @key{ESC}}.)
The reason for this rule is that a non-prefix binding for @key{ESC} in
In some other systems there is a convention of choosing variable names
that begin and end with @samp{*}. We don't use that convention in Emacs
Lisp, so please don't use it in your programs. (Emacs uses such names
-only for program-generated buffers.) The users will find Emacs more
+only for special-purpose buffers.) The users will find Emacs more
coherent if all libraries use the same conventions.
@item
Don't make a habit of putting close-parentheses on lines by themselves;
Lisp programmers find this disconcerting. Once in a while, when there
is a sequence of many consecutive close-parentheses, it may make sense
-to split them in one or two significant places.
+to split the sequence in one or two significant places.
@item
Please put a copyright notice on the file if you give copies to anyone.
@node Documentation Tips
@section Tips for Documentation Strings
- Here are some tips for the writing of documentation strings.
+@tindex checkdoc-minor-mode
+@findex checkdoc-minor-mode
+ Here are some tips and conventions for the writing of documentation
+strings. You can check many of these conventions by running the command
+@kbd{M-x checkdoc-minor-mode}.
@itemize @bullet
@item
When a documentation string refers to a Lisp symbol, write it as it
would be printed (which usually means in lower case), with single-quotes
around it. For example: @samp{lambda}. There are two exceptions: write
-t and nil without single-quotes. (In this manual, we normally do use
-single-quotes for those symbols.)
+t and nil without single-quotes. (In this manual, we use a different
+convention, with single-quotes for all symbols.)
@end ifinfo
+For example:
+
+@example
+The value of `swim-speed' specifies how fast to swim.
+Possible values are t for high speed, nil for low speed,
+and `medium' for medium speed.
+@end example
+
@item
Don't write key sequences directly in documentation strings. Instead,
use the @samp{\\[@dots{}]} construct to stand for them. For example,
@end group
@end smallexample
-Every function that has no documentation string (because it is use only
-internally within the package it belongs to), should have instead a
-two-semicolon comment right before the function, explaining what the
-function does and how to call it properly. Explain precisely what each
-argument means and how the function interprets its possible values.
+Every function that has no documentation string (presumably one that is
+used only internally within the package it belongs to), should have
+instead a two-semicolon comment right before the function, explaining
+what the function does and how to call it properly. Explain precisely
+what each argument means and how the function interprets its possible
+values.
@item ;;;
Comments that start with three semicolons, @samp{;;;}, should start at
@noindent
The indentation commands of the Lisp modes in Emacs, such as @kbd{M-;}
-(@code{indent-for-comment}) and @key{TAB} (@code{lisp-indent-line})
+(@code{indent-for-comment}) and @key{TAB} (@code{lisp-indent-line}),
automatically indent comments according to these conventions,
depending on the number of semicolons. @xref{Comments,,
Manipulating Comments, emacs, The GNU Emacs Manual}.
;; Keywords: docs
;; This file is part of GNU Emacs.
-@var{copying permissions}@dots{}
+@dots{}
+;; Free Software Foundation, Inc., 59 Temple Place - Suite 330,
+;; Boston, MA 02111-1307, USA.
@end group
@end smallexample
* Setting Variables:: Storing new values in variables.
* Variable Scoping:: How Lisp chooses among local and global values.
* Buffer-Local Variables:: Variable values in effect only in one buffer.
+* Frame-Local Variables:: Variable values in effect only in one frame.
+* Future Local Variables:: New kinds of local values we might add some day.
@end menu
@node Global Variables
@noindent
assuming the @code{setq} form shown above has already been executed.
- If you do another @code{setq}, the new value replaces the old one:
+ If you do set the same variable again, the new value replaces the old
+one:
@example
@group
@vindex t
@kindex setting-constant
- In Emacs Lisp, certain symbols normally evaluate to themselves.
-These include @code{nil} and @code{t}, as well as any symbol whose
-name starts with @samp{:}.
-
- The symbols @code{nil} and @code{t} @emph{always} evaluate to
-themselves. These symbols cannot be rebound, nor can their values be
-changed. Any attempt to change the value of @code{nil} or @code{t}
-signals a @code{setting-constant} error.
+ In Emacs Lisp, certain symbols normally evaluate to themselves. These
+include @code{nil} and @code{t}, as well as any symbol whose name starts
+with @samp{:}. These symbols cannot be rebound, nor can their values be
+changed. Any attempt to set or bind @code{nil} or @code{t} signals a
+@code{setting-constant} error. The same is true for a symbol whose name
+starts with @samp{:}, except that you are allowed to set such symbol to
+itself.
@example
@group
@end group
@end example
+@tindex keyword-symbols-constant-flag
+@defvar keyword-symbols-constant-flag
+If this variable is @code{nil}, you are allowed to set and bind symbols
+whose names start with @samp{:} as you wish. This is to make it
+possible to run old Lisp programs which do that.
+@end defvar
+
@node Local Variables
@section Local Variables
@cindex binding local variables
Global variables have values that last until explicitly superseded
with new values. Sometimes it is useful to create variable values that
-exist temporarily---only while within a certain part of the program.
+exist temporarily---only until a certain part of the program finishes.
These values are called @dfn{local}, and the variables so used are
called @dfn{local variables}.
If you set a variable (such as with @code{setq}) while it is local,
this replaces the local value; it does not alter the global value, or
-previous local values that are shadowed. To model this behavior, we
+previous local values, that are shadowed. To model this behavior, we
speak of a @dfn{local binding} of the variable as well as a local value.
The local binding is a conceptual place that holds a local value.
A variable can have more than one local binding at a time (for
example, if there are nested @code{let} forms that bind it). In such a
case, the most recently created local binding that still exists is the
-@dfn{current binding} of the variable. (This is called @dfn{dynamic
-scoping}; see @ref{Variable Scoping}.) If there are no local bindings,
-the variable's global binding is its current binding. We also call the
-current binding the @dfn{most-local existing binding}, for emphasis.
-Ordinary evaluation of a symbol always returns the value of its current
-binding.
+@dfn{current binding} of the variable. (This rule is called
+@dfn{dynamic scoping}; see @ref{Variable Scoping}.) If there are no
+local bindings, the variable's global binding is its current binding.
+We sometimes call the current binding the @dfn{most-local existing
+binding}, for emphasis. Ordinary evaluation of a symbol always returns
+the value of its current binding.
The special forms @code{let} and @code{let*} exist to create
local bindings.
@example
@group
-(makunbound 'x) ; @r{Make the global value}
- ; @r{of @code{x} void.}
+(makunbound 'x) ; @r{Make the global value of @code{x} void.}
@result{} x
@end group
@group
local binding, since all the constructs that create local bindings
create them with values. In this case, the voidness lasts at most as
long as the binding does; when the binding is removed due to exit from
-the construct that made it, the previous or global binding is reexposed
-as usual, and the variable is no longer void unless the newly reexposed
-binding was void all along.
+the construct that made it, the previous local or global binding is
+reexposed as usual, and the variable is no longer void unless the newly
+reexposed binding was void all along.
@smallexample
@group
If the first character of @var{doc-string} is @samp{*}, it means that
this variable is considered a user option. This lets users set the
-variable conventiently using the commands @code{set-variable} and
+variable conveniently using the commands @code{set-variable} and
@code{edit-options}. However, it is better to use @code{defcustom}
-instead of @code{defvar}, for user option variables, to specify
+instead of @code{defvar} for user option variables, so you can specify
customization information. @xref{Customization}.
Here are some examples. This form defines @code{foo} but does not
@noindent
This method has several benefits. First, if the user quits while
loading the file, the variable is either still uninitialized or
-initialized properly, never in-between. If it is uninitialized,
+initialized properly, never in-between. If it is still uninitialized,
reloading the file will initialize it properly. Second, reloading the
file once the variable is initialized will not alter it; that is
important if the user has run hooks to alter part of the contents (such
@end example
@noindent
-This code sets the variable, then alters it, but only if the variable
-had been @code{ni}. If the user quits just after the @code{setq}, that
-leaves the variable neither correctly initialized nor void nor
-@code{nil}. Once that happens, reloading the file will not initialize
-the variable; it will remain incomplete.
+This code sets the variable, then alters it, but it does so in more than
+one step. If the user quits just after the @code{setq}, that leaves the
+variable neither correctly initialized nor void nor @code{nil}. Once
+that happens, reloading the file will not initialize the variable; it
+will remain incomplete.
@node Accessing Variables
@section Accessing Variable Values
@end group
@end example
-A @code{void-variable} error is signaled if @var{symbol} has neither a
-local binding nor a global one.
+A @code{void-variable} error is signaled if the current binding of
+@var{symbol} is void.
@end defun
@node Setting Variables
The argument @var{symbol} is not implicitly quoted; @code{add-to-list}
is an ordinary function, like @code{set} and unlike @code{setq}. Quote
the argument yourself if that is what you want.
+@end defun
Here's a scenario showing how to use @code{add-to-list}:
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:
works) may help you understand dynamic binding. This technique is
called @dfn{deep binding} and was used in early Lisp systems.
- Suppose there is a stack of bindings: variable-value pairs. At entry
-to a function or to a @code{let} form, we can push bindings onto the stack
-for the arguments or local variables created there. We can pop those
-bindings from the stack at exit from the binding construct.
+ Suppose there is a stack of bindings, which are variable-value pairs.
+At entry to a function or to a @code{let} form, we can push bindings
+onto the stack for the arguments or local variables created there. We
+can pop those bindings from the stack at exit from the binding
+construct.
We can find the value of a variable by searching the stack from top to
bottom for a binding for that variable; the value from that binding is
@cindex buffer-local variables
Global and local variable bindings are found in most programming
-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. (A few variables have bindings that
-are local to a given X terminal; see @ref{Multiple Displays}.)
+languages in one form or another. Emacs also supports additional,
+unusual kinds of variable binding: @dfn{buffer-local} bindings, which
+apply only in one buffer, and frame-local bindings, which apply only in
+one frame. Having different values for a variable in different buffers
+and/or frames is an important customization method.
+
+ This section describes buffer-local bindings; for frame-local
+bindings, see the following section, @ref{Frame-Local Variables}. (A few
+variables have bindings that are local to a X terminal; see
+@ref{Multiple Displays}.)
@menu
* Intro to Buffer-Local:: Introduction and concepts.
* Creating Buffer-Local:: Creating and destroying buffer-local bindings.
* Default Value:: The default value is seen in buffers
- that don't have their own local values.
+ that don't have their own buffer-local values.
@end menu
@node Intro to Buffer-Local
A variable can have buffer-local bindings in some buffers but not in
other buffers. The default binding is shared by all the buffers that
-don't have their own bindings for the variable. If you set the variable
-in a buffer that does not have a buffer-local binding for it, this sets
-the default binding, so the new value is visible in all the buffers that
-see the default binding.
+don't have their own bindings for the variable. (This includes all
+newly created buffers.) If you set the variable in a buffer that does
+not have a buffer-local binding for it, this sets the default binding
+(assuming there are no frame-local bindings to complicate the matter),
+so the new value is visible in all the buffers that see the default
+binding.
The most common use of buffer-local bindings is for major modes to change
variables that control the behavior of commands. For example, C mode and
Lisp mode both set the variable @code{paragraph-start} to specify that only
blank lines separate paragraphs. They do this by making the variable
buffer-local in the buffer that is being put into C mode or Lisp mode, and
-then setting it to the new value for that mode.
+then setting it to the new value for that mode. @xref{Major Modes}.
The usual way to make a buffer-local binding is with
-@code{make-local-variable}, which is what major mode commands use. This
-affects just the current buffer; all other buffers (including those yet to
-be created) continue to share the default value.
+@code{make-local-variable}, which is what major mode commands typically
+use. This affects just the current buffer; all other buffers (including
+those yet to be created) will continue to share the default value unless
+they are explicitly given their own buffer-local bindings.
@cindex automatically buffer-local
A more powerful operation is to mark the variable as
precisely, the effect is that setting the variable automatically makes
the variable local to the current buffer if it is not already so. All
buffers start out by sharing the default value of the variable as usual,
-but any @code{setq} creates a buffer-local binding for the current
+but setting the variable creates a buffer-local binding for the current
buffer. The new value is stored in the buffer-local binding, leaving
-the default binding untouched. The default value can no longer be
-changed with @code{setq} in this buffer; you need to use
-@code{setq-default} to do that.
+the default binding untouched. This means that the default value cannot
+be changed with @code{setq} in any buffer; the only way to change it is
+with @code{setq-default}.
@strong{Warning:} When a variable has buffer-local values in one or
more buffers, you can get Emacs very confused by binding the variable
buffer-local binding of buffer @samp{b}.
When a file specifies local variable values, these become buffer-local
-values when you visit the file. @xref{Auto Major Mode}.
+values when you visit the file. @xref{File Variables,,, emacs, The
+GNU Emacs Manual}.
@node Creating Buffer-Local
@subsection Creating and Deleting Buffer-Local Bindings
@end example
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.
+variable does not work reliably, unless the buffer in which you do this
+is not current either on entry to or exit from the @code{let}. This is
+because @code{let} does not distinguish between different kinds of
+bindings; it knows only which variable the binding was made for.
If the variable is terminal-local, this function signals an error. Such
variables cannot have buffer-local bindings as well. @xref{Multiple
buffer-local, so that any subsequent attempt to set it will make it
local to the current buffer at the time.
-The value returned is @var{variable}.
+A peculiar wrinkle of this feature is that binding the variable (with
+@code{let} or other binding constructs) does not create a buffer-local
+binding for it. Only setting the variable (with @code{set} or
+@code{setq}) does so.
-@strong{Note:} It is a mistake to use @code{make-variable-buffer-local}
-for user-option variables, simply because users @emph{might} want to
-customize them differently in different buffers. Users can make any
-variable local, when they wish to.
+The value returned is @var{variable}.
-The main use of @code{make-variable-buffer-local} is when a variable is
-used for internal purposes, and the Lisp program depends on having
-separate values in separate buffers.
+@strong{Warning:} Don't assume that you should use
+@code{make-variable-buffer-local} for user-option variables, simply
+because users @emph{might} want to customize them differently in
+different buffers. Users can make any variable local, when they wish
+to. It is better to leave the choice to them.
+
+The time to use @code{make-variable-buffer-local} is when it is crucial
+that no two buffers ever share the same binding. For example, when a
+variable is used for internal purposes in a Lisp program which depends
+on having separate values in separate buffers, then using
+@code{make-variable-buffer-local} can be the best solution.
@end deffn
@defun local-variable-p variable &optional buffer
@defun buffer-local-variables &optional buffer
This function returns a list describing the buffer-local variables in
-buffer @var{buffer}. It returns an association list (@pxref{Association
-Lists}) in which each association contains one buffer-local variable and
-its value. When a buffer-local variable is void in @var{buffer}, then
-it appears directly in the resulting list. If @var{buffer} is omitted,
-the current buffer is used.
+buffer @var{buffer}. (If @var{buffer} is omitted, the current buffer is
+used.) It returns an association list (@pxref{Association Lists}) in
+which each element contains one buffer-local variable and its value.
+However, when a variable's buffer-local binding in @var{buffer} is void,
+then the variable appears directly in the resulting list.
@example
@group
of @code{fundamental-mode-abbrev-table}.
The very first thing this function does is run the normal hook
-@code{change-major-mode-hook} (@pxref{Major Mode Conventions}).
+@code{change-major-mode-hook} (see below).
Every major mode command begins by calling this function, which has the
effect of switching to Fundamental mode and erasing most of the effects
@code{kill-all-local-variables} returns @code{nil}.
@end defun
+@defvar change-major-mode-hook
+The function @code{kill-all-local-variables} runs this normal hook
+before it does anything else. This gives major modes a way to arrange
+for something special to be done if the user switches to a different
+major mode. For best results, make this variable buffer-local, so that
+it will disappear after doing its job and will not interfere with the
+subsequent major mode. @xref{Hooks}.
+@end defvar
+
@c Emacs 19 feature
@cindex permanent local variable
A buffer-local variable is @dfn{permanent} if the variable name (a
The global value of a variable with buffer-local bindings is also
called the @dfn{default} value, because it is the value that is in
-effect except when specifically overridden.
+effect whenever neither the current buffer nor the selected frame has
+its own binding for the variable.
The functions @code{default-value} and @code{setq-default} access and
change a variable's default value regardless of whether the current
@c Emacs 19 feature
The special forms @code{defvar} and @code{defconst} also set the
default value (if they set the variable at all), rather than any
-buffer-local value.
+buffer-local or frame-local value.
@defun default-value symbol
This function returns @var{symbol}'s default value. This is the value
-that is seen in buffers that do not have their own values for this
-variable. If @var{symbol} is not buffer-local, this is equivalent to
-@code{symbol-value} (@pxref{Accessing Variables}).
+that is seen in buffers and frames that do not have their own values for
+this variable. If @var{symbol} is not buffer-local, this is equivalent
+to @code{symbol-value} (@pxref{Accessing Variables}).
@end defun
@c Emacs 19 feature
@example
@group
;; @r{In buffer @samp{foo}:}
-(make-local-variable 'local)
- @result{} local
+(make-local-variable 'buffer-local)
+ @result{} buffer-local
@end group
@group
-(setq local 'value-in-foo)
+(setq buffer-local 'value-in-foo)
@result{} value-in-foo
@end group
@group
-(setq-default local 'new-default)
+(setq-default buffer-local 'new-default)
@result{} new-default
@end group
@group
-local
+buffer-local
@result{} value-in-foo
@end group
@group
-(default-value 'local)
+(default-value 'buffer-local)
@result{} new-default
@end group
@group
;; @r{In (the new) buffer @samp{bar}:}
-local
+buffer-local
@result{} new-default
@end group
@group
-(default-value 'local)
+(default-value 'buffer-local)
@result{} new-default
@end group
@group
-(setq local 'another-default)
+(setq buffer-local 'another-default)
@result{} another-default
@end group
@group
-(default-value 'local)
+(default-value 'buffer-local)
@result{} another-default
@end group
@group
;; @r{Back in buffer @samp{foo}:}
-local
+buffer-local
@result{} value-in-foo
-(default-value 'local)
+(default-value 'buffer-local)
@result{} another-default
@end group
@end example
@end group
@end example
@end defun
+
+@node Frame-Local Variables
+@section Frame-Local Variables
+
+ Just as variables can have buffer-local bindings, they can also have
+frame-local bindings. These bindings belong to one frame, and are in
+effect when that frame is selected. Frame-local bindings are actually
+frame parameters: you create a frame-local binding in a specific frame
+by calling @code{modify-frame-parameters} and specifying the variable
+name as the parameter name.
+
+ To enable frame-local bindings for a certain variable, call the function
+@code{make-variable-frame-local}.
+
+@defun make-variable-frame-local variable
+Enable the use of frame-local bindings for @var{variable}. This does
+not in itself create any frame-local bindings for the variable; however,
+if some frame already has a value for @var{variable} as a frame
+parameter, that value automatically becomes a frame-local binding.
+
+If the variable is terminal-local, this function signals an error. Such
+variables cannot have buffer-local bindings as well. @xref{Multiple
+Displays}. A few variables that are implemented specially in Emacs
+can be (and usually are) buffer-local, but can never be frame-local.
+@end defun
+
+ Buffer-local bindings take precedence over frame-local bindings. Thus,
+consider a variable @code{foo}: if the current buffer has a buffer-local
+binding for @code{foo}, that binding is active; otherwise, if the
+selected frame has a frame-local binding for @code{foo}, that binding is
+active; otherwise, the default binding of @code{foo} is active.
+
+ Here is an example. First we prepare a few bindings for @code{foo}:
+
+@example
+(setq f1 (selected-frame))
+(make-variable-frame-local 'foo)
+
+;; @r{Make a buffer-local binding for @code{foo} in @samp{b1}.}
+(set-buffer (get-buffer-create "b1"))
+(make-local-variable 'foo)
+(setq foo '(b 1))
+
+;; @r{Make a frame-local binding for @code{foo} in a new frame.}
+;; @r{Store that frame in @code{f2}.}
+(setq f2 (make-frame))
+(modify-frame-parameters f2 '((foo . (f 2))))
+@end example
+
+ Now we examine @code{foo} in various contexts. Whenever the
+buffer @samp{b1} is current, its buffer-local binding is in effect,
+regardless of the selected frame:
+
+@example
+(select-frame f1)
+(set-buffer (get-buffer-create "b1"))
+foo
+ @result{} (b 1)
+
+(select-frame f2)
+(set-buffer (get-buffer-create "b1"))
+foo
+ @result{} (b 1)
+@end example
+
+@noindent
+Otherwise, the frame gets a chance to provide the binding; when frame
+@code{f2} is selected, its frame-local binding is in effect:
+
+@example
+(select-frame f2)
+(set-buffer (get-buffer "*scratch*"))
+foo
+ @result{} (f 2)
+@end example
+
+@noindent
+When neither the current buffer nor the selected frame provides
+a binding, the default binding is used:
+
+@example
+(select-frame f1)
+(set-buffer (get-buffer "*scratch*"))
+foo
+ @result{} nil
+@end example
+
+@noindent
+When the active binding of a variable is a frame-local binding, setting
+the variable changes that binding. You can observe the result with
+@code{frame-parameters}:
+
+@example
+(select-frame f2)
+(set-buffer (get-buffer "*scratch*"))
+(setq foo 'nobody)
+(assq 'foo (frame-parameters f2))
+ @result{} (foo . nobody)
+@end example
+
+@node Future Local Variables
+@section Possible Future Local Variables
+
+ We have considered the idea of bindings that are local to a category
+of frames---for example, all color frames, or all frames with dark
+backgrounds. We have not implemented them because it is not clear that
+this feature is really useful. You can get more or less the same
+results by adding a function to @code{after-make-frame-hook}, set up to
+define a particular frame parameter according to the appropriate
+conditions for each frame.
+
+ It would also be possible to implement window-local bindings. We
+don't know of many situations where they would be useful, and it seems
+that indirect buffers (@pxref{Indirect Buffers}) with buffer-local
+bindings offer a way to handle these situations more robustly.
+
+ If sufficient application is found for either of these two kinds of
+local bindings, we will provide it in a subsequent Emacs version.
+
+
@end smallexample
Normally, Emacs indicates the border between two side-by-side windows
-with a scroll bar (@pxref{X Frame Parameters,Scroll Bars}) or @samp{|}
+with a scroll bar (@pxref{Window Frame Parameters,Scroll Bars}) or @samp{|}
characters. The display table can specify alternative border
characters; see @ref{Display Tables}.
@end deffn
deletes any windows that aren't part of that configuration.
When you delete a window, the space it took up is given to one
-adjacent sibling. (In Emacs version 18, the space was divided evenly
-among all the siblings.)
+adjacent sibling.
@c Emacs 19 feature
@defun window-live-p window
@end defun
@deffn Command delete-window &optional window
-This function removes @var{window} from the display. If @var{window}
-is omitted, then the selected window is deleted. An error is signaled
-if there is only one window when @code{delete-window} is called.
-
-This function returns @code{nil}.
-
-When @code{delete-window} is called interactively, @var{window}
-defaults to the selected window.
+This function removes @var{window} from display, and returns @code{nil}.
+If @var{window} is omitted, then the selected window is deleted. An
+error is signaled if there is only one window when @code{delete-window}
+is called.
@end deffn
@deffn Command delete-other-windows &optional window
deleting the other windows in that frame. If @var{window} is omitted or
@code{nil}, then the selected window is used by default.
-The result is @code{nil}.
+The return value is @code{nil}.
@end deffn
@deffn Command delete-windows-on buffer &optional frame
the change persists.
Each frame, at any time, has a window selected within the frame. This
-macro only saves @emph{the} selected window; it does not save anything
+macro saves only @emph{the} selected window; it does not save anything
about other frames. If the @var{forms} select some other frame and
alter the window selected within it, the change persists.
@end defmac
@deffn Command other-window count
This function selects the @var{count}th following window in the cyclic
-order. If count is negative, then it selects the @minus{}@var{count}th
-preceding window. It returns @code{nil}.
+order. If count is negative, then it moves back @minus{}@var{count}
+windows in the cycle, rather than forward. It returns @code{nil}.
In an interactive call, @var{count} is the numeric prefix argument.
@end deffn
Do not use the functions in this section in order to make a buffer
current so that a Lisp program can access or modify it; they are too
drastic for that purpose, since they change the display of buffers in
-windows, which is gratuitous and will surprise the user. Instead, use
+windows, which would be gratuitous and surprise the user. Instead, use
@code{set-buffer} (@pxref{Current Buffer}) and @code{save-excursion}
(@pxref{Excursions}), which designate buffers as current for programmed
access without affecting the display of buffers in windows.
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
+Normally the specified buffer is put at the front of the buffer list
+(both the selected frame's buffer list and the frame-independent buffer
+list). This affects the operation of @code{other-buffer}. However, if
@var{norecord} is non-@code{nil}, this is not done. @xref{The Buffer
List}.
@tindex buffer-display-count
@defvar buffer-display-count
-This variable is always local in each buffer. When the buffer is
+This variable is always buffer-local in each buffer. When the buffer is
created, @code{buffer-display-count} has value 0. Each time the buffer
is displayed in a window, that increments the value of
@code{buffer-display-count}.
@c Emacs 19 feature
@cindex dedicated window
A window can be marked as ``dedicated'' to its buffer. Then
-@code{display-buffer} does not try to use that window.
+@code{display-buffer} will not try to use that window to display any
+other buffer.
@defun window-dedicated-p window
This function returns @code{t} if @var{window} is marked as dedicated;
description of @code{count-lines} in @ref{Text Lines}.
@end defun
-@defun window-end &optional window
+@defun window-end &optional window update
This function returns the position of the end of the display in window
@var{window}. If @var{window} is @code{nil}, the selected window is
used.
Simply changing the buffer text or moving point does not update the
value that @code{window-end} returns. The value is updated only when
-Emacs redisplays and redisplay actually finishes.
+Emacs redisplays and redisplay completes without being preempted.
If the last redisplay of @var{window} was preempted, and did not finish,
Emacs does not know the position of the end of display in that window.
-In that case, this function returns a value that is not correct. In a
-future version, @code{window-end} will return @code{nil} in that case.
-@ignore
-in that case, this function returns @code{nil}. You can compute where
-the end of the window @emph{would} have been, if redisplay had finished,
-like this:
+In that case, this function returns @code{nil}.
-@example
-(save-excursion
- (goto-char (window-start window))
- (vertical-motion (1- (window-height window))
- window)
- (point))
-@end example
-@end ignore
+If you @var{update} is non-@code{nil}, @code{window-end} always returns
+an up-to-date value for where the window ends. If the saved value is
+valid, @code{window-end} returns that; otherwise it computes the correct
+value by scanning the buffer text.
@end defun
@defun set-window-start window position &optional noforce
The following three functions return size information about a window:
@defun window-height &optional window
-This function returns the number of lines in @var{window}, including
-its mode line. If @var{window} fills its entire frame, this is one less
-than the value of @code{frame-height} on that frame (since the last line
-is always reserved for the minibuffer).
+This function returns the number of lines in @var{window}, including its
+mode line. If @var{window} fills its entire frame, this is typically
+one less than the value of @code{frame-height} on that frame (since the
+last line is always reserved for the minibuffer).
If @var{window} is @code{nil}, the function uses the selected window.
This function checks whether a particular frame position falls within
the window @var{window}.
-@need 3000
-The argument @var{coordinates} is a cons cell of this form:
-
-@example
-(@var{x} . @var{y})
-@end example
-
-@noindent
-The coordinates @var{x} and @var{y} are measured in characters, and
-count from the top left corner of the screen or frame.
+The argument @var{coordinates} is a cons cell of the form @code{(@var{x}
+. @var{y})}. The coordinates @var{x} and @var{y} are measured in
+characters, and count from the top left corner of the screen or frame.
The value returned by @code{coordinates-in-window-p} is non-@code{nil}
if the coordinates are inside @var{window}. The value also indicates
current window configuration, including the number of windows, their
sizes and current buffers, which window is the selected window, and for
each window the displayed buffer, the display-start position, and the
-positions of point and the mark. An exception is made for point in the
+positions of point and the mark. It also includes the values of
+@code{window-min-height}, @code{window-min-width} and
+@code{minibuffer-scroll-window}. An exception is made for point in the
current buffer, whose value is not saved.
@end defun
This function restores the configuration of windows and buffers as
specified by @var{configuration}. The argument @var{configuration} must
be a value that was previously returned by
-@code{current-window-configuration}. This function operates on the
-frame for which @var{configuration} was made, whether that frame is
-selected or not.
-
-This function always counts as a window size change and triggers
-execution of the @code{window-size-change-functions}. (It doesn't know
-how to tell whether the new configuration actually differs from the old
-one.)
+@code{current-window-configuration}. This configuration is restored in
+the frame from which @var{configuration} was made, whether that frame is
+selected or not. This always counts as a window size change and
+triggers execution of the @code{window-size-change-functions}
+(@pxref{Window Hooks}), because @code{set-window-configuration} doesn't
+know how to tell whether the new configuration actually differs from the
+old one.
+
+If the frame which @var{configuration} was saved from is dead, all this
+function does is restore the three variables @code{window-min-height},
+@code{window-min-width} and @code{minibuffer-scroll-window}.
Here is a way of using this function to get the same effect
as @code{save-window-excursion}:
@defun window-configuration-p object
This function returns @code{t} if @var{object} is a window configuration.
+@end defun
+
+@defun compare-window-configurations config1 config2
+This function compares two window configurations as regards the
+structure of windows, but ignores the values of point and mark and the
+saved scrolling positions---it can return @code{t} even if those
+aspects differ.
+
+The function @code{equal} can also compare two window configurations; it
+regards configurations as unequal if they differ in any respect, even a
+saved point or mark.
@end defun
Primitives to look inside of window configurations would make sense,
switching buffers in the window, and changing the size of the window.
The first two actions run @code{window-scroll-functions}; the last runs
@code{window-size-change-functions}. The paradigmatic use of these
-hooks is Lazy Lock mode; see @ref{Support Modes, Lazy Lock, Font Lock
-Support Modes, emacs, The GNU Emacs Manual}.
+hooks is in the implementation of Lazy Lock mode; see @ref{Support
+Modes, Lazy Lock, Font Lock Support Modes, emacs, The GNU Emacs Manual}.
@defvar window-scroll-functions
This variable holds a list of functions that Emacs should call before
projects / emacs.git / commitdiff