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

*** empty log message ***

Browse source
This commit is contained in:
Richard M. Stallman 1999-09-17 06:59:04 +00:00
parent 106217c660
commit 8241495da5
42 changed files with 3996 additions and 1589 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
lispref/abbrevs.texi
View file

@ -4,7 +4,7 @@
@c See the file elisp.texi for copying conditions.
@setfilename ../info/abbrevs
@node Abbrevs, Processes, Syntax Tables, Top
@chapter Abbrevs And Abbrev Expansion
@chapter Abbrevs and Abbrev Expansion
@cindex abbrev
@cindex abbrev table

11
lispref/advice.texi
View file

@ -174,6 +174,9 @@ actually called. If more than one piece of advice specifies an argument
list, then the first one (the one with the smallest position) found in
the list of all classes of advice is used.
@xref{Argument Access in Advice}, for more information about argument
lists and advice.
The remaining elements, @var{flags}, are symbols that specify further
information about how to use this piece of advice. Here are the valid
symbols and their meanings:
@ -210,7 +213,7 @@ unless subsequently explicitly enabled. @xref{Enabling Advice}.
Activate advice for @var{function} when this @code{defadvice} is
compiled or macroexpanded. This generates a compiled advised definition
according to the current advice state, which will be used during
activation if appropriate.
activation if appropriate. @xref{Preactivation}.
This is useful only if this @code{defadvice} is byte-compiled.
@end table
@ -301,7 +304,9 @@ specified @var{class}, then @var{position} specifies where in the list
to put the new piece of advice. The value of @var{position} can either
be @code{first}, @code{last}, or a number (counting from 0 at the
beginning of the list). Numbers outside the range are mapped to the
closest extreme position.
beginning or the end of the range, whichever is closer. The
@var{position} value is ignored when redefining an existing piece of
advice.
If @var{function} already has a piece of @var{advice} with the same
name, then the position argument is ignored and the old advice is
@ -339,7 +344,7 @@ the command also compiles the combined definition which implements the
advice.
@deffn Command ad-activate function &optional compile
This command activates the advice for @var{function}.
This command activates all the advice defined for @var{function}.
@end deffn
To activate advice for a function whose advice is already active is not

424
lispref/anti.texi
View file

@ -1,248 +1,226 @@
@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 1998 Free Software Foundation, Inc.
@c Copyright (C) 1999 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@node Antinews, Index, Standard Hooks, Top
@appendix Emacs 19 Antinews
@appendix Emacs 20 Antinews
For those users who live backwards in time, here is information about
downgrading to Emacs version 19.34. We hope you will enjoy the greater
simplicity that results from the absence of many Emacs 20 features. In
the following section, we carry this information back as far as Emacs
19.29, for which the previous printed edition of this manual was made.
downgrading to Emacs version 20.4. We hope you will enjoy the greater
simplicity that results from the absence of many Emacs 21 features. In
the following section, we carry this information back to Emacs
20.3, for which the previous printed edition of this manual was made.
@section Old Lisp Features in Emacs 19
Here are the most important of the features that you will learn
to do without in Emacs 19:
@section Old Lisp Features in Emacs 20
@itemize @bullet
@item
In a great simplification, Emacs 19 supports ASCII characters only.
There are no multibyte characters, character sets, language
environments, coding systems, or input methods; all the functions that
specifically relate to them are gone as well.
Valid character codes for text must be in the range 0 through 255.
Within this range, there are no invalid character codes.
The @code{push} and @code{pop} macros are not defined.
@item
The Custom facility has been replaced with a much simpler and more
general method of defining user option variables. Instead of
@code{defcustom}, which requires you to specify each user option's data
type and classify options into groups, all you have to do is write a
@code{defvar}. You should still start the documentation string with
@samp{*}, though.
You can't display images in buffers. (Emacs is meant for editing text.)
With no images, there are no display margins, and no tool bars.
@item
The @code{display} text property has no special meaning; you can use it
freely in Lisp programs, with no effects except what you implement for
yourself. With no images, who needs the @code{display} text property?
@item
Faces have fewer attributes. The attributes @code{:family},
@code{:height}, @code{:width}, @code{:weight}, and @code{:slant},
have been replaced with a font name, a ``bold'' flag, and an
``italic'' flag.
The attributes @code{:overline}, @code{:strike-through}
and @code{:box} have been eliminated too.
With fewer font attributes, there are no functions
@code{set-face-attribute} and @code{face-attribute}. Instead, you
access these attributes using functions such as @code{face-font}, and
set them with functions such as @code{set-face-font}. (These functions
were available in Emacs 21, but are not as useful there.)
@item
There are no facilities for playing sound. This means Emacs will
respect your peace and quiet, aside from occasional beeps.
@item
Regular expressions do not support the POSIX character classes
such as @samp{[:alpha:]}. All characters are created equal.
@item
Hash tables have been eliminated; use alists instead.
@item
The Lisp printer does not detect and report circular structure. That is
ok, because the Lisp reader cannot recreate circular structure anyway.
However, there is a library @samp{cust-print.el} which can report
circular structure.
@item
Emacs provides its own implementation of scroll bars, instead
of using those of the X toolkit. They always use the frame foreground
and background colors, so you cannot specify different colors for
the scroll bars.
@item
For simplicity, all ASCII characters now have the same height and width.
(Certain characters, such as Chinese characters, always have have twice
the standard width.) All characters are created equal.
@item
Tooltips operate using ordinary Emacs frames.
@item
Areas of the mode line are not mouse-sensitive; however, some mouse
commands are available for the mode line as a whole.
@item
Windows cannot have header lines. Conversely, there is no way to turn
off the mode line of a window unless it is a minibuffer.
@item
Plain dashes are the only separators you can use in a menu.
@item
Vertical fractional scrolling does not exist.
@item
The functions @code{format} and @code{message} ignore and discard text
properties.
@item
Colors are supported only on window systems, not on text-only terminals.
So the support functions for colors on text-only terminals are
not needed.
@item
The functions @code{color-values}, @code{color-defined-p} and
@code{defined-colors} have been renamed to @code{x-color-values},
@code{x-color-defined-p} and @code{x-defined-colors}.
@item
Windows cannot be made fixed-width or fixed-height;
Emacs will adjust the size of all windows when it needs to.
@item
The minibuffer prompt does not actually appear in content of the
minibuffer; it is displayed specially in the minibuffer window.
@item
The ``exclusive open'' feature of @code{write-region}
has been eliminated; any non-@code{nil} value for the seventh
argument now means to ask the user for confirmation.
@item
The function @code{buffer-size} always reports on the
current buffer.
@item
The function @code{assoc-delete-all} has itself been deleted.
So there!
@item
The variable @code{small-temporary-file-directory} has no special
meaning. There's only one variable for specifying which directory to
use for temporary files, @code{temporary-file-directory}, but not all
Emacs features use it anyway. Some use the @code{TMP} environment
variable, and some use the @code{TMPDIR} environment variable.
@item
The variable @code{inhibit-modification-hooks}
has no special meaning.
@item
The hook @code{fontification-functions} has been eliminated,
but there are other hooks, such as @code{window-scroll-functions},
that you can use to do a similar job.
@item
The variable @code{redisplay-dont-pause}
has no special meaning.
@item
The hook @code{calendar-move-hook} has been deleted.
@item
The function @code{move-to-column} treats any non-@code{nil}
second argument just like @code{t}.
@end itemize
@section Old Lisp Features in Emacs 20.3
Here are the most important of the features that you will learn
to do without in Emacs 20.3:
Here are changes in the Lisp language itself:
@itemize @bullet
@item
Symbols whose names start with @samp{:} are no longer special
in any way. They start out void, like most other symbols.
The functions @code{line-beginning-position} and @code{line-end-position}
have been eliminated.
@item
The macros @code{when} and @code{unless} have been deleted.
The functions @code{directory-files-and-attributes},
@code{file-attributes-lessp}, and @code{file-expand-wildcards}, have
been eliminated.
@item
The functions @code{caar}, @code{cadr}, @code{cdar} and @code{cddr}
no longer exist.
The functions @code{decode-coding-region} and @code{encode-coding-region}
leave text properties untouched, in case that is useful. (It rarely makes
any sense, though.)
@item
The function @code{functionp} is now gone. If you don't know
by now whether something is a function, Emacs can't tell you.
@end itemize
Here are changes in handling strings and text.
@itemize @bullet
@item
The function @code{substring} works only on strings, not on vectors.
@item
There are no more character categories.
@item
When you compare strings with @code{equal}, it now compares
their string properties as well as their text. All must match,
or the strings are not equal.
@item
@code{format-time-string} no longer supports specified field width
or specified padding.
@item
The functions @code{split-string} and @code{string} no longer exist.
Neither does @code{store-substring} or @code{sref}.
@item
All printing characters have the same width. Therefore, we have deleted
@code{char-width}, @code{string-width} and
@code{truncate-string-to-width}.
@item
We have eliminated the functions @code{next-char-property-change} and
@code{previous-char-property-change} also.
@item
Syntax parsing now determines the syntax of each character from the
syntax table alone---not from text properties. This makes the syntax
codes @samp{|} and @samp{!}, which were meant for use with text
properties, useless; so we have deleted them.
@item
In the function @code{parse-partial-sexp}, passing @code{syntax-table}
as the sixth argument @var{commentstop} no longer has any special meaning.
And the return value has only eight elements.
@end itemize
Here are changes in other areas of Emacs Lisp:
@itemize @bullet
@item
The macros @code{save-current-buffer}, @code{with-current-buffer},
@code{with-temp-buffer}, @code{with-temp-file}, @code{save-selected-window},
and @code{with-output-to-string} are gone.
@item
The easy-mmode facility for defining minor modes is gone too.
@item
Process filters and sentinels must explicitly save the match data, with
@code{save-match-data}, or they will clobber the match data and
something horrible will happen.
@item
As part of our effort to loosen up, @code{batch-byte-compile-file} no
longer returns a nonzero status code if there is a compilation error.
@item
The ``mail user agent'' feature is gone.
@item
We have removed the functions @code{add-to-invisibility-spec} and
@code{remove-from-invisibility-spec}, so you should manipulate
the value of @code{buffer-invisibility-spec} by hand.
@item
The functions @code{face-documentation}, @code{face-bold-p},
@code{face-italic-p}, @code{set-face-bold-p}, @code{set-face-italic-p}
are gone. Instead, use @code{make-face-bold} and friends.
@item
All the functions that operate on a file now discard an extra redundant
directory name from the beginning of the file name---just like
@code{substitute-in-file-name}.
@item
We have got rid of the function @code{access-file}.
@item
Most of the minibuffer input functions no longer take a default value as
an argument. Also, they do not discard text properties from the result.
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.
@item
Wave goodbye to the hooks @code{before-make-frame-hook},
@code{after-make-frame-functions}, and
@code{window-configuration-change-hook},
@item
The functions and variables that deal with MS Windows NT/95
have been renamed to start with @samp{win32-} instead of @samp{w32-}.
This is because we admire Microsoft more each day as we go back
into the past.
@end itemize
@section Onward into the Past!
Here we go even further back, as far as Emacs 19.29, for which the
previous printed edition of the Emacs Lisp manual was made.
@itemize @bullet
@item
There are no char-tables or bool-vectors. Syntax tables, display
tables, and case tables are all vectors now, and the value of
@code{keyboard-translate-table} should be a vector or a string.
@item
There is only one kind of marker. When you insert text at the place
where a marker points, the marker always ends up before that text,
unless you use @code{insert-before-markers}, which puts all the markers
after the inserted text.
@item
There is no function @code{overlays-in}.
@item
The variable @code{print-length} applies only to lists, not to
vectors or strings.
@item
The function @code{convert-standard-filename} no longer exists, so each
Lisp package must independently figure out which file names to use for
its initialization files on each kind of operating system.
@item
The macro @code{with-timeout} has been eliminated, along with the
function @code{y-or-n-p-with-timeout}. Idle timers don't exist at all;
instead, maybe you can use @code{post-command-idle-hook} to do some of
the same job.
@item
The functions @code{keymap-parent} and @code{set-keymap-parent} are
gone. We expect keymaps to recognize their own parents.
@item
When you delete text and then undo a deletion, markers that were
originally inside the deleted text end up either at the beginning
or the end of it---not back in their original places.
@item
The interactive specification @samp{N} is gone now.
@item
There is no more @code{safe-length}. Don't try to be so safe! Did you
expect to live forever?
@item
We got rid of @code{insert-file-contents-literally}, because
programmers are too literal-minded anyway.
@item
As part of our continuing effort to help Lisp programmers to relax, we
threw out the function @code{error-message-string}. Don't worry so much
about errors! We all make mistakes.
@item
The keymap @code{special-event-map} is gone, because Emacs has no more
special events. If you want to hold a party in Emacs, please let us
know.
@item
You can't do date arithmetic with @code{encode-time} any more.
@item
The functions @code{command-execute} and @code{call-interactively} no
longer accept the optional argument @var{keys}.
@item
@code{get-buffer-window-list} is gone as well.
@item
With the function @code{replace-match}, you can only replace the whole
match, not a subexpression of it.
@item
We eliminated the hooks @code{buffer-access-fontify-functions},
@code{window-scroll-functions}, and @code{redisplay-end-trigger-functions}.
The functions @code{position-bytes} and @code{byte-to-position} have
been eliminated.
@item
Temporary buffers made with @code{with-output-to-temp-buffer} are now
modifiable by default, and use Fundamental mode rather than Help mode.
@item
The functions @code{sref} interprets its @var{index} argument as a
number of bytes, not a number of characters. And the function
@code{char-bytes} actually tries to report on the number of bytes that a
character occupies.
@item
The function @code{process-running-child-p} has been eliminated.
@item
The function @code{interrupt-process} and similar functions no longer do
anything special when the second argument is @code{lambda}.
@item
The function @code{define-prefix-command} accepts only two arguments.
@item
The meaning of the second argument to @code{read-char},
@code{read-event}, and @code{read-char-exclusive} has been reversed:
they use the current input method if the argument is if @code{nil}.
@item
The function @code{with-temp-message} has been eliminated.
@item
The function @code{clear-this-command-keys} has been eliminated.
@item
The functions @code{gap-position} and @code{gap-size} have been eliminated.
@item
In @code{modify-face}, an argument of @code{(nil)} has no special
meaning.
@item
The base64 conversion functions have been eliminated.
@item
Wildcard support has been eliminated from @code{find-file}
and allied functions.
@item
@code{file-attributes} returns the file size and the file inode number
only as a simple integer.
@end itemize

91
lispref/backups.texi
View file

@ -179,6 +179,19 @@ This variable is significant only if @code{backup-by-copying} is
non-@code{nil}.
@end defvar
@defvar backup-by-copying-when-privileged-mismatch
This variable, if non-@code{nil}, specifies the same behavior as
@code{backup-by-copying-when-mismatch}, but only for certain user-id
values: namely, those less than or equal to a certain number. You set
this variable to that number.
Thus, if you set @code{backup-by-copying-when-privileged-mismatch}
to 0, backup by copying is done for the superuser only,
when necessary to prevent a change in the owner of the file.
The default is 200.
@end defvar
@node Numbered Backups
@subsection Making and Deleting Numbered Backup Files
@ -393,8 +406,8 @@ integer. Otherwise, it turns auto-saving off.
@defun auto-save-file-name-p filename
This function returns a non-@code{nil} value if @var{filename} is a
string that could be the name of an auto-save file. It works based on
knowledge of the naming convention for auto-save files: a name that
string that could be the name of an auto-save file. It assumes
the usual naming convention for auto-save files: a name that
begins and ends with hash marks (@samp{#}) is a possible auto-save file
name. The argument @var{filename} should not contain a directory part.
@ -433,8 +446,8 @@ correspondingly.
This function returns the file name to use for auto-saving the current
buffer. This is just the file name with hash marks (@samp{#}) prepended
and appended to it. This function does not look at the variable
@code{auto-save-visited-file-name} (described below); you should check
that before calling this function.
@code{auto-save-visited-file-name} (described below); callers of this
function should check that variable first.
@example
@group
@ -475,10 +488,11 @@ file that you are editing. Normally, this variable is @code{nil}, so
auto-save files have distinct names that are created by
@code{make-auto-save-file-name}.
When you change the value of this variable, the value does not take
effect until the next time auto-save mode is reenabled in any given
buffer. If auto-save mode is already enabled, auto-saves continue to go
in the same file name until @code{auto-save-mode} is called again.
When you change the value of this variable, the new value does not take
effect in an existing buffer until the next time auto-save mode is
reenabled in it. If auto-save mode is already enabled, auto-saves
continue to go in the same file name until @code{auto-save-mode} is
called again.
@end defvar
@defun recent-auto-save-p
@ -493,18 +507,18 @@ function returns @code{nil}.
@end defun
@defopt auto-save-interval
The value of this variable is the number of characters that Emacs
reads from the keyboard between auto-saves. Each time this many more
characters are read, auto-saving is done for all buffers in which it is
The value of this variable specifies how often to do auto-saving, in
terms of number of input events. Each time this many additional input
events are read, Emacs does auto-saving for all buffers in which that is
enabled.
@end defopt
@defopt auto-save-timeout
The value of this variable is the number of seconds of idle time that
should cause auto-saving. Each time the user pauses for this long,
Emacs auto-saves any buffers that need it. (Actually, the specified
timeout is multiplied by a factor depending on the size of the current
buffer.)
Emacs does auto-saving for all buffers in which that is enabled.
(Actually, the specified timeout is multiplied by a factor depending on
the size of the current buffer.)
@end defopt
@defvar auto-save-hook
@ -552,14 +566,15 @@ nothing.
@defvar buffer-saved-size
The value of this buffer-local variable is the length of the current
buffer as of the last time it was read in, saved, or auto-saved. This is
buffer, when it was last read in, saved, or auto-saved. This is
used to detect a substantial decrease in size, and turn off auto-saving
in response.
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.
If it is @minus{}1, that means auto-saving is temporarily shut off in
this buffer due to a substantial decrease in size. Explicitly saving
the buffer stores a positive value in this variable, thus reenabling
auto-saving. Turning auto-save mode off or on also updates this
variable, so that the substantial decrease in size is forgotten.
@end defvar
@defvar auto-save-list-file-name
@ -570,14 +585,14 @@ enabled. The first line gives the name of the visited file (it's empty
if the buffer has none), and the second gives the name of the auto-save
file.
If Emacs exits normally, it deletes this file. If Emacs crashes, you
When Emacs exits normally, it deletes this file; if Emacs crashes, you
can look in the file to find all the auto-save files that might contain
work that was otherwise lost. The @code{recover-session} command uses
these files.
this file to find them.
The default name for this file is in your home directory and starts with
@samp{.saves-}. It also contains the Emacs process @sc{id} and the host
name.
The default name for this file specifies your home directory and starts
with @samp{.saves-}. It also contains the Emacs process @sc{id} and the
host name.
@end defvar
@node Reverting
@ -594,10 +609,10 @@ file on disk. This action undoes all changes since the file was visited
or saved.
By default, if the latest auto-save file is more recent than the visited
file, @code{revert-buffer} asks the user whether to use that instead.
But if the argument @var{ignore-auto} is non-@code{nil}, then only the
the visited file itself is used. Interactively, @var{ignore-auto} is
@code{t} unless there is a numeric prefix argument; thus, the
file, and the argument @var{ignore-auto} is non-@code{nil},
@code{revert-buffer} asks the user whether to use that auto-save
instead. When you invoke this command interactively, @var{ignore-auto}
is @code{t} unless there is a numeric prefix argument; thus, the
interactive default is to check the auto-save file.
Normally, @code{revert-buffer} asks for confirmation before it changes
@ -608,9 +623,9 @@ Reverting tries to preserve marker positions in the buffer by using the
replacement feature of @code{insert-file-contents}. If the buffer
contents and the file contents are identical before the revert
operation, reverting preserves all the markers. If they are not
identical, reverting does change the buffer; then it preserves the
markers in the unchanged text (if any) at the beginning and end of the
buffer. Preserving any additional markers would be problematical.
identical, reverting does change the buffer; in that case, it preserves
the markers in the unchanged text (if any) at the beginning and end of
the buffer. Preserving any additional markers would be problematical.
@end deffn
You can customize how @code{revert-buffer} does its work by setting
@ -618,10 +633,10 @@ these variables---typically, as buffer-local variables.
@defvar revert-without-query
This variable holds a list of files that should be reverted without
query. The value is a list of regular expressions. If a file name
matches one of these regular expressions, then @code{revert-buffer}
reverts the file without asking the user for confirmation, if the file
has changed on disk and the buffer is not modified.
query. The value is a list of regular expressions. If the visited file
name matches one of these regular expressions, and the file has changed
on disk but the buffer is not modified, then @code{revert-buffer}
reverts the file without asking the user for confirmation.
@end defvar
@defvar revert-buffer-function
@ -637,20 +652,20 @@ regenerate the contents.
@end defvar
@defvar revert-buffer-insert-file-contents-function
The value of this variable, if non-@code{nil}, is the function to use to
The value of this variable, if non-@code{nil}, specifies the function to use to
insert the updated contents when reverting this buffer. The function
receives two arguments: first the file name to use; second, @code{t} if
the user has asked to read the auto-save file.
@end defvar
@defvar before-revert-hook
This normal hook is run by @code{revert-buffer} before actually
This normal hook is run by @code{revert-buffer} before
inserting the modified contents---but only if
@code{revert-buffer-function} is @code{nil}.
@end defvar
@defvar after-revert-hook
This normal hook is run by @code{revert-buffer} after actually inserting
This normal hook is run by @code{revert-buffer} after inserting
the modified contents---but only if @code{revert-buffer-function} is
@code{nil}.
@end defvar

58
lispref/buffers.texi
View file

@ -10,7 +10,7 @@
A @dfn{buffer} is a Lisp object containing text to be edited. Buffers
are used to hold the contents of files that are being visited; there may
also be buffers that are not visiting files. While several buffers may
exist at one time, exactly one buffer is designated the @dfn{current
exist at one time, only one buffer is designated the @dfn{current
buffer} at any time. Most editing commands act on the contents of the
current buffer. Each buffer, including the current buffer, may or may
not be displayed in any windows.
@ -18,7 +18,7 @@ not be displayed in any windows.
@menu
* Buffer Basics:: What is a buffer?
* Current Buffer:: Designating a buffer as current
so primitives will access its contents.
so that primitives will access its contents.
* Buffer Names:: Accessing and changing buffer names.
* Buffer File Name:: The buffer file name indicates which file is visited.
* Buffer Modification:: A buffer is @dfn{modified} if it needs to be saved.
@ -39,8 +39,8 @@ not be displayed in any windows.
@ifinfo
A @dfn{buffer} is a Lisp object containing text to be edited. Buffers
are used to hold the contents of files that are being visited; there may
also be buffers that are not visiting files. While several buffers may
exist at one time, exactly one buffer is designated the @dfn{current
also be buffers that are not visiting files. Although several buffers
normally exist, only one buffer is designated the @dfn{current
buffer} at any time. Most editing commands act on the contents of the
current buffer. Each buffer, including the current buffer, may or may
not be displayed in any windows.
@ -103,12 +103,12 @@ current, to prevent confusion: the buffer that the cursor is in when
Emacs reads a command is the buffer that the command will apply to.
(@xref{Command Loop}.) Therefore, @code{set-buffer} is not the way to
switch visibly to a different buffer so that the user can edit it. For
this, you must use the functions described in @ref{Displaying Buffers}.
that, you must use the functions described in @ref{Displaying Buffers}.
However, Lisp functions that change to a different current buffer
@strong{Note:} Lisp functions that change to a different current buffer
should not depend on the command loop to set it back afterwards.
Editing commands written in Emacs Lisp can be called from other programs
as well as from the command loop. It is convenient for the caller if
as well as from the command loop; it is convenient for the caller if
the subroutine does not change which buffer is current (unless, of
course, that is the subroutine's purpose). Therefore, you should
normally use @code{set-buffer} within a @code{save-current-buffer} or
@ -153,9 +153,9 @@ binding. Otherwise, use @code{save-current-buffer} or
@code{save-excursion} to make sure that the buffer current at the
beginning is current again whenever the variable is unbound.
It is not reliable to change the current buffer back with
@code{set-buffer}, because that won't do the job if a quit happens while
the wrong buffer is current. Here is what @emph{not} to do:
Do not rely on using @code{set-buffer} to change the current buffer
back, because that won't do the job if a quit happens while the wrong
buffer is current. Here is what @emph{not} to do:
@example
@group
@ -192,10 +192,9 @@ This function returns the current buffer.
@end defun
@defun set-buffer buffer-or-name
This function makes @var{buffer-or-name} the current buffer. It does
not display the buffer in the currently selected window or in any other
window, so the user cannot necessarily see the buffer. But Lisp
programs can in any case work on it.
This function makes @var{buffer-or-name} the current buffer. This does
not display the buffer in any window, so the user cannot necessarily see
the buffer. But Lisp programs will now operate on it.
This function returns the buffer identified by @var{buffer-or-name}.
An error is signaled if @var{buffer-or-name} does not identify an
@ -302,18 +301,15 @@ Ordinarily, @code{rename-buffer} signals an error if @var{newname} is
already in use. However, if @var{unique} is non-@code{nil}, it modifies
@var{newname} to make a name that is not in use. Interactively, you can
make @var{unique} non-@code{nil} with a numeric prefix argument.
One application of this command is to rename the @samp{*shell*} buffer
to some other name, thus making it possible to create a second shell
buffer under the name @samp{*shell*}.
(This is how the command @code{rename-uniquely} is implemented.)
@end deffn
@defun get-buffer buffer-or-name
This function returns the buffer specified by @var{buffer-or-name}.
If @var{buffer-or-name} is a string and there is no buffer with that
name, the value is @code{nil}. If @var{buffer-or-name} is a buffer, it
is returned as given. (That is not very useful, so the argument is usually
a name.) For example:
is returned as given; that is not very useful, so the argument is usually
a name. For example:
@example
@group
@ -374,7 +370,7 @@ supplied, it defaults to the current buffer.
@defvar buffer-file-name
This buffer-local variable contains the name of the file being visited
in the current buffer, or @code{nil} if it is not visiting a file. It
is a permanent local, unaffected by @code{kill-local-variables}.
is a permanent local variable, unaffected by @code{kill-local-variables}.
@example
@group
@ -621,7 +617,7 @@ the read-only flag with @kbd{C-x C-q}.
@item
Modes such as Dired and Rmail make buffers read-only when altering the
contents with the usual editing commands is probably a mistake.
contents with the usual editing commands would probably be a mistake.
The special commands of these modes bind @code{buffer-read-only} to
@code{nil} (with @code{let}) or bind @code{inhibit-read-only} to
@ -649,7 +645,7 @@ of the list (comparison is done with @code{eq}).
@deffn Command toggle-read-only
This command changes whether the current buffer is read-only. It is
intended for interactive use; don't use it in programs. At any given
intended for interactive use; do not use it in programs. At any given
point in a program, you should know whether you want the read-only flag
on or off; so you can set @code{buffer-read-only} explicitly to the
proper value, @code{t} or @code{nil}.
@ -857,8 +853,8 @@ text space available for other use.
The buffer object for the buffer that has been killed remains in
existence as long as anything refers to it, but it is specially marked
so that you cannot make it current or display it. Killed buffers retain
their identity, however; two distinct buffers, when killed, remain
distinct according to @code{eq}.
their identity, however; if you kill two distinct buffers, they remain
distinct according to @code{eq} although both are dead.
If you kill a buffer that is current or displayed in a window, Emacs
automatically selects or displays some other buffer instead. This means
@ -916,9 +912,9 @@ Buffer foo.changed modified; kill anyway? (yes or no) @kbd{yes}
After confirming unsaved changes, @code{kill-buffer} calls the functions
in the list @code{kill-buffer-query-functions}, in order of appearance,
with no arguments. The buffer being killed is the current buffer when
they are called. The idea is that these functions ask for confirmation
from the user for various nonstandard reasons. If any of them returns
@code{nil}, @code{kill-buffer} spares the buffer's life.
they are called. The idea of this feature is that these functions will
ask for confirmation from the user. If any of them returns @code{nil},
@code{kill-buffer} spares the buffer's life.
@end defvar
@defvar kill-buffer-hook
@ -951,7 +947,7 @@ base buffer; changes made by editing either one are visible immediately
in the other. This includes the text properties as well as the characters
themselves.
But in all other respects, the indirect buffer and its base buffer are
In all other respects, the indirect buffer and its base buffer are
completely separate. They have different names, different values of
point, different narrowing, different markers and overlays (though
inserting or deleting text in either buffer relocates the markers and
@ -959,8 +955,8 @@ overlays for both), different major modes, and different buffer-local
variables.
An indirect buffer cannot visit a file, but its base buffer can. If
you try to save the indirect buffer, that actually works by saving the
base buffer.
you try to save the indirect buffer, that actually saves the base
buffer.
Killing an indirect buffer has no effect on its base buffer. Killing
the base buffer effectively kills the indirect buffer in that it cannot

6
lispref/calendar.texi
View file

@ -117,6 +117,10 @@ terminal.
A similar normal hook, @code{today-invisible-calendar-hook} is run if
the current date is @emph{not} visible in the window.
@vindex calendar-move-hook
Starting in Emacs 21, each of the calendar cursor motion commands
runs the hook @code{calendar-move-hook} after it moves the cursor.
@node Holiday Customizing
@section Customizing the Holidays
@ -776,7 +780,7 @@ can use
@noindent
and the fancy diary will show
@smallexample
Ruth & Ed's anniversary
Ed's anniversary
@end smallexample
@noindent
both on December 15 and on December 22.

68
lispref/commands.texi
View file

@ -322,7 +322,7 @@ You can use @samp{e} more than once in a single command's interactive
specification. If the key sequence that invoked the command has
@var{n} events that are lists, the @var{n}th @samp{e} provides the
@var{n}th such event. Events that are not lists, such as function keys
and @sc{ASCII} characters, do not count where @samp{e} is concerned.
and @sc{ascii} characters, do not count where @samp{e} is concerned.
@item f
A file name of an existing file (@pxref{File Names}). The default
@ -760,7 +760,7 @@ last-command-event
@end example
@noindent
The value is 5 because that is the @sc{ASCII} code for @kbd{C-e}.
The value is 5 because that is the @sc{ascii} code for @kbd{C-e}.
The alias @code{last-command-char} exists for compatibility with
Emacs version 18.
@ -834,7 +834,7 @@ An input character event consists of a @dfn{basic code} between 0 and
@item meta
The
@tex
$2^{27}$
@math{2^{27}}
@end tex
@ifinfo
2**27
@ -845,57 +845,57 @@ typed with the meta key held down.
@item control
The
@tex
$2^{26}$
@math{2^{26}}
@end tex
@ifinfo
2**26
@end ifinfo
bit in the character code indicates a non-@sc{ASCII}
bit in the character code indicates a non-@sc{ascii}
control character.
@sc{ASCII} control characters such as @kbd{C-a} have special basic
@sc{ascii} control characters such as @kbd{C-a} have special basic
codes of their own, so Emacs needs no special bit to indicate them.
Thus, the code for @kbd{C-a} is just 1.
But if you type a control combination not in @sc{ASCII}, such as
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
@tex
$2^{26}$
@math{2^{26}}
@end tex
@ifinfo
2**26
@end ifinfo
(assuming the terminal supports non-@sc{ASCII}
(assuming the terminal supports non-@sc{ascii}
control characters).
@item shift
The
@tex
$2^{25}$
@math{2^{25}}
@end tex
@ifinfo
2**25
@end ifinfo
bit in the character code indicates an @sc{ASCII} control
bit in the character code indicates an @sc{ascii} control
character typed with the shift key held down.
For letters, the basic code itself indicates upper versus lower case;
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
@sc{ascii} character set whenever possible, Emacs avoids using the
@tex
$2^{25}$
@math{2^{25}}
@end tex
@ifinfo
2**25
@end ifinfo
bit for those characters.
However, @sc{ASCII} provides no way to distinguish @kbd{C-A} from
However, @sc{ascii} provides no way to distinguish @kbd{C-A} from
@kbd{C-a}, so Emacs uses the
@tex
$2^{25}$
@math{2^{25}}
@end tex
@ifinfo
2**25
@ -906,7 +906,7 @@ bit in @kbd{C-A} and not in
@item hyper
The
@tex
$2^{24}$
@math{2^{24}}
@end tex
@ifinfo
2**24
@ -917,7 +917,7 @@ typed with the hyper key held down.
@item super
The
@tex
$2^{23}$
@math{2^{23}}
@end tex
@ifinfo
2**23
@ -928,7 +928,7 @@ typed with the super key held down.
@item alt
The
@tex
$2^{22}$
@math{2^{22}}
@end tex
@ifinfo
2**22
@ -966,10 +966,10 @@ function keys:
@table @asis
@item @code{backspace}, @code{tab}, @code{newline}, @code{return}, @code{delete}
These keys correspond to common @sc{ASCII} control characters that have
These keys correspond to common @sc{ascii} control characters that have
special keys on most keyboards.
In @sc{ASCII}, @kbd{C-i} and @key{TAB} are the same character. If the
In @sc{ascii}, @kbd{C-i} and @key{TAB} are the same character. If the
terminal can distinguish between them, Emacs conveys the distinction to
Lisp programs by representing the former as the integer 9, and the
latter as the symbol @code{tab}.
@ -981,7 +981,7 @@ character @kbd{C-i}) also applies to @code{tab}. Likewise for the other
symbols in this group. The function @code{read-char} likewise converts
these events into characters.
In @sc{ASCII}, @key{BS} is really @kbd{C-h}. But @code{backspace}
In @sc{ascii}, @key{BS} is really @kbd{C-h}. But @code{backspace}
converts into the character code 127 (@key{DEL}), not into code 8
(@key{BS}). This is what most users prefer.
@ -1657,7 +1657,7 @@ 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}$
@math{2^{27}}
@end tex
@ifinfo
2**27
@ -1677,14 +1677,14 @@ in the string unchanged.
@item
The meta variants of those characters, with codes in the range of
@tex
$2^{27}$
@math{2^{27}}
@end tex
@ifinfo
2**27
@end ifinfo
to
@tex
$2^{27} + 127$,
@math{2^{27} + 127},
@end tex
@ifinfo
2**27+127,
@ -1692,14 +1692,14 @@ $2^{27} + 127$,
can also go in the string, but you must change their
numeric values. You must set the
@tex
$2^{7}$
@math{2^{7}}
@end tex
@ifinfo
2**7
@end ifinfo
bit instead of the
@tex
$2^{27}$
@math{2^{27}}
@end tex
@ifinfo
2**27
@ -1708,7 +1708,7 @@ 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.
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
@ -1869,7 +1869,7 @@ Echo Area}.
If @var{inherit-input-method} is non-@code{nil}, then the current input
method (if any) is employed to make it possible to enter a
non-@sc{ASCII} character. Otherwise, input method handling is disabled
non-@sc{ascii} character. Otherwise, input method handling is disabled
for reading this event.
If @code{cursor-in-echo-area} is non-@code{nil}, then @code{read-event}
@ -1899,7 +1899,7 @@ user generates an event which is not a character (i.e. a mouse click or
function key event), @code{read-char} signals an error. The arguments
work as in @code{read-event}.
In the first example, the user types the character @kbd{1} (@sc{ASCII}
In the first example, the user types the character @kbd{1} (@sc{ascii}
code 49). The second example shows a keyboard macro definition that
calls @code{read-char} from the minibuffer using @code{eval-expression}.
@code{read-char} reads the keyboard macro's very next character, which
@ -2078,7 +2078,7 @@ This variable records the last terminal input event read, whether
as part of a command or explicitly by a Lisp program.
In the example below, the Lisp program reads the character @kbd{1},
@sc{ASCII} code 49. It becomes the value of @code{last-input-event},
@sc{ascii} code 49. It becomes the value of @code{last-input-event},
while @kbd{C-e} (we assume @kbd{C-x C-e} command is used to evaluate
this expression) remains the value of @code{last-command-event}.
@ -2171,12 +2171,8 @@ period measured in milliseconds. This adds to the period specified by
@var{seconds}. If the system doesn't support waiting fractions of a
second, you get an error if you specify nonzero @var{millisec}.
@cindex forcing redisplay
Redisplay is always preempted if input arrives, and does not happen at
all if input is available before it starts. Thus, there is no way to
force screen updating if there is pending input; however, if there is no
input pending, you can force an update with no delay by using
@code{(sit-for 0)}.
The expression @code{(sit-for 0)} is a convenient way to request a
redisplay, without any delay. @xref{Forcing Redisplay}.
If @var{nodisp} is non-@code{nil}, then @code{sit-for} does not
redisplay, but it still returns as soon as input is available (or when

94
lispref/control.texi
View file

@ -20,8 +20,8 @@ write several forms in succession in the body of a function, or at top
level in a file of Lisp code---the forms are executed in the order
written. We call this @dfn{textual order}. For example, if a function
body consists of two forms @var{a} and @var{b}, evaluation of the
function evaluates first @var{a} and then @var{b}, and the function's
value is the value of @var{b}.
function evaluates first @var{a} and then @var{b}. The result of
evaluating @var{b} becomes the value of the function.
Explicit control structures make possible an order of execution other
than sequential.
@ -60,9 +60,9 @@ control construct of Lisp.
@noindent
and it says to execute the forms @var{a}, @var{b}, @var{c}, and so on, in
that order. These forms are called the body of the @code{progn} form.
that order. These forms are called the @dfn{body} of the @code{progn} form.
The value of the last form in the body becomes the value of the entire
@code{progn}.
@code{progn}. @code{(progn)} returns @code{nil}.
@cindex implicit @code{progn}
In the early days of Lisp, @code{progn} was the only way to execute
@ -72,8 +72,8 @@ body of a function, where (at that time) only one form was allowed. So
the body of a function was made into an ``implicit @code{progn}'':
several forms are allowed just as in the body of an actual @code{progn}.
Many other control structures likewise contain an implicit @code{progn}.
As a result, @code{progn} is not used as often as it used to be. It is
needed now most often inside an @code{unwind-protect}, @code{and},
As a result, @code{progn} is not used as much as it was many years ago.
It is needed now most often inside an @code{unwind-protect}, @code{and},
@code{or}, or in the @var{then}-part of an @code{if}.
@defspec progn forms@dots{}
@ -265,6 +265,7 @@ For example,
@example
@group
(setq a 5)
(cond ((eq a 'hack) 'foo)
(t "default"))
@result{} "default"
@ -272,8 +273,8 @@ For example,
@end example
@noindent
This expression is a @code{cond} which returns @code{foo} if the value
of @code{a} is @code{hack}, and returns the string @code{"default"} otherwise.
This @code{cond} expression returns @code{foo} if the value of @code{a}
is @code{hack}, and returns the string @code{"default"} otherwise.
@end defspec
Any conditional construct can be expressed with @code{cond} or with
@ -310,11 +311,14 @@ order written.
If any of the @var{conditions} evaluates to @code{nil}, then the result
of the @code{and} must be @code{nil} regardless of the remaining
@var{conditions}; so @code{and} returns right away, ignoring the
remaining @var{conditions}.
@var{conditions}; so @code{and} returns @code{nil} right away, ignoring
the remaining @var{conditions}.
If all the @var{conditions} turn out non-@code{nil}, then the value of
the last of them becomes the value of the @code{and} form.
the last of them becomes the value of the @code{and} form. Just
@code{(and)}, with no @var{conditions}, returns @code{t}, appropriate
because all the @var{conditions} turned out non-@code{nil}. (Think
about it; which one did not?)
Here is an example. The first condition returns the integer 1, which is
not @code{nil}. Similarly, the second condition returns the integer 2,
@ -368,10 +372,13 @@ right away, ignoring the remaining @var{conditions}. The value it
returns is the non-@code{nil} value of the condition just evaluated.
If all the @var{conditions} turn out @code{nil}, then the @code{or}
expression returns @code{nil}.
expression returns @code{nil}. Just @code{(or)}, with no
@var{conditions}, returns @code{nil}, appropriate because all the
@var{conditions} turned out @code{nil}. (Think about it; which one
did not?)
For example, this expression tests whether @code{x} is either 0 or
@code{nil}:
For example, this expression tests whether @code{x} is either
@code{nil} or the integer zero:
@example
(or (eq x nil) (eq x 0))
@ -446,9 +453,10 @@ The value of a @code{while} form is always @code{nil}.
@end group
@end example
If you would like to execute something on each iteration before the
end-test, put it together with the end-test in a @code{progn} as the
first argument of @code{while}, as shown here:
To write a ``repeat...until'' loop, which will execute something on each
iteration and then do the end-test, put the body followed by the
end-test in a @code{progn} as the first argument of @code{while}, as
shown here:
@example
@group
@ -560,9 +568,10 @@ With the return point in effect, @code{catch} evaluates the forms of the
error or nonlocal exit) the value of the last body form is returned from
the @code{catch}.
If a @code{throw} is done within @var{body} specifying the same value
@var{tag}, the @code{catch} exits immediately; the value it returns is
whatever was specified as the second argument of @code{throw}.
If a @code{throw} is executed during the execution of @var{body},
specifying the same value @var{tag}, the @code{catch} form exits
immediately; the value it returns is whatever was specified as the
second argument of @code{throw}.
@end defspec
@defun throw tag value
@ -640,13 +649,6 @@ printed. Finally the second body form in the outer @code{catch}, which is
Now let's change the argument given to @code{catch2}:
@example
@group
(defun catch2 (tag)
(catch tag
(throw 'hack 'yes)))
@result{} catch2
@end group
@group
(catch 'hack
(print (catch2 'quux))
@ -709,6 +711,11 @@ buffer. You can also signal errors explicitly with the functions
considered an error, but it is handled almost like an error.
@xref{Quitting}.
The error message should state what is wrong (``File does not
exist''), not how things ought to be (``File must exist''). The
convention in Emacs Lisp is that error messages should start with a
capital letter, but should not end with any sort of punctuation.
@defun error format-string &rest args
This function signals an error with an error message constructed by
applying @code{format} (@pxref{String Conversion}) to
@ -852,7 +859,7 @@ above, there is one handler, and it specifies one condition name,
The search for an applicable handler checks all the established handlers
starting with the most recently established one. Thus, if two nested
@code{condition-case} forms offer to handle the same error, the inner of
the two will actually handle it.
the two gets to handle it.
If an error is handled by some @code{condition-case} form, this
ordinarily prevents the debugger from being run, even if
@ -881,10 +888,11 @@ totally unpredictable, such as when the program evaluates an expression
read from the user.
Error signaling and handling have some resemblance to @code{throw} and
@code{catch}, but they are entirely separate facilities. An error
cannot be caught by a @code{catch}, and a @code{throw} cannot be handled
by an error handler (though using @code{throw} when there is no suitable
@code{catch} signals an error that can be handled).
@code{catch} (@pxref{Catch and Throw}), but they are entirely separate
facilities. An error cannot be caught by a @code{catch}, and a
@code{throw} cannot be handled by an error handler (though using
@code{throw} when there is no suitable @code{catch} signals an error
that can be handled).
@defspec condition-case var protected-form handlers@dots{}
This special form establishes the error handlers @var{handlers} around
@ -1127,9 +1135,9 @@ the value of the last @var{body} form, after it evaluates the
@var{cleanup-forms}. If the @var{body} forms do not finish,
@code{unwind-protect} does not return any value in the normal sense.
Only the @var{body} is actually protected by the @code{unwind-protect}.
If any of the @var{cleanup-forms} themselves exits nonlocally (e.g., via
a @code{throw} or an error), @code{unwind-protect} is @emph{not}
Only the @var{body} is protected by the @code{unwind-protect}. If any
of the @var{cleanup-forms} themselves exits nonlocally (via a
@code{throw} or an error), @code{unwind-protect} is @emph{not}
guaranteed to evaluate the rest of them. If the failure of one of the
@var{cleanup-forms} has the potential to cause trouble, then protect it
with another @code{unwind-protect} around that form.
@ -1167,13 +1175,13 @@ 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
creates a process (@pxref{Processes}) to try to establish a connection
to a remote machine. As the function @code{ftp-login} is highly
susceptible to numerous problems that the writer of the function cannot
anticipate, it is protected with a form that guarantees deletion of the
process in the event of failure. Otherwise, Emacs might fill up with
useless subprocesses.
Here is an actual example derived from an FTP package. It creates a
process (@pxref{Processes}) to try to establish a connection to a remote
machine. As the function @code{ftp-login} is highly susceptible to
numerous problems that the writer of the function cannot anticipate, it
is protected with a form that guarantees deletion of the process in the
event of failure. Otherwise, Emacs might fill up with useless
subprocesses.
@smallexample
@group
@ -1188,7 +1196,7 @@ useless subprocesses.
@end group
@end smallexample
This example actually has a small bug: if the user types @kbd{C-g} to
This example has a small bug: if the user types @kbd{C-g} to
quit, and the quit happens immediately after the function
@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,

63
lispref/customize.texi
View file

@ -19,7 +19,7 @@ definitions---as well as face definitions (@pxref{Defining Faces}).
@end menu
@node Common Keywords
@section Common Keywords for All Kinds of Items
@section Common Item Keywords
All kinds of customization declarations (for variables and groups, and
for faces) accept keyword arguments for specifying various information.
@ -31,8 +31,8 @@ The keyword @code{:tag} is an exception because any given item can only
display one name.
@table @code
@item :tag @var{name}
Use @var{name}, a string, instead of the item's name, to label the item
@item :tag @var{label}
Use @var{label}, a string, instead of the item's name, to label the item
in customization menus and buffers.
@item :group @var{group}
@ -42,7 +42,7 @@ Put this customization item in group @var{group}. When you use
If you use this keyword more than once, you can put a single item into
more than one group. Displaying any of those groups will show this
item. Be careful not to overdo this!
item. Please don't overdo this, since the result would be annoying.
@item :link @var{link-data}
Include an external link after the documentation string for this item.
@ -113,7 +113,8 @@ keyword.
@tindex defgroup
Declare @var{group} as a customization group containing @var{members}.
Do not quote the symbol @var{group}. The argument @var{doc} specifies
the documentation string for the group.
the documentation string for the group. It should not start with a
@samp{*} as in @code{defcustom}; that convention is for variables only.
The argument @var{members} is a list specifying an initial set of
customization items to be members of the group. However, most often
@ -165,12 +166,20 @@ turn this feature back on, if someone would like to do the work.
@tindex defcustom
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.
string for the variable; it should normally start with a @samp{*}. This
marks the variable, for other purposes, as one that users may want to
customize.
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 evaluated on more
than one occasion.
When you evaluate a @code{defcustom} form with @kbd{C-M-x} in Emacs Lisp
mode (@code{eval-defun}), a special feature of @code{eval-defun}
arranges to set the variable unconditionally, without testing whether
its value is void. (The same feature applies to @code{defvar}.)
@xref{Defining Variables}.
@end defmac
@code{defcustom} accepts the following additional keywords:
@ -277,7 +286,8 @@ options for @code{emacs-lisp-mode-hook}, but not by editing its
definition. You can do it thus:
@example
(custom-add-option 'emacs-lisp-mode-hook 'my-lisp-mode-initialization)
(custom-add-option 'emacs-lisp-mode-hook
'my-lisp-mode-initialization)
@end example
@defun custom-add-option symbol option
@ -392,10 +402,9 @@ edit both the key and the value of each pair.
You can specify the key and value types like this:
@example
(alist :key-type @var{key-type}
:value-type @var{value-type})
@end example
@smallexample
(alist :key-type @var{key-type} :value-type @var{value-type})
@end smallexample
@noindent
where @var{key-type} and @var{value-type} are customization type
@ -414,9 +423,9 @@ The argument to the @code{:options} keywords should be a list of option
specifications. Ordinarily, the options are simply atoms, which are the
specified keys. For example:
@example
@smallexample
:options '("foo" "bar" "baz")
@end example
@end smallexample
@noindent
specifies that there are three ``known'' keys, namely @code{"foo"},
@ -428,9 +437,9 @@ You can specify this by using a list instead of an atom in the option
specification. The first element will specify the key, like before,
while the second element will specify the value type.
@example
@smallexample
:options '("foo" ("bar" integer) "baz")
@end example
@end smallexample
Finally, you may want to change how the key is presented. By default,
the key is simply shown as a @code{const}, since the user cannot change
@ -440,36 +449,36 @@ you may want to use a more specialized type for presenting the key, like
This is done by using a customization type specification instead of a
symbol for the key.
@example
@smallexample
:options '("foo" ((function-item some-function) integer) "baz")
@end example
@end smallexample
Many alists use lists with two elements, instead of cons cells. For
example,
@example
@smallexample
(defcustom list-alist '(("foo" 1) ("bar" 2) ("baz" 3))
"Each element is a list of the form (KEY VALUE).")
@end example
@end smallexample
@noindent
instead of
@example
@smallexample
(defcustom cons-alist '(("foo" . 1) ("bar" . 2) ("baz" . 3))
"Each element is a cons-cell (KEY . VALUE).")
@end example
@end smallexample
Because of the way lists are implemented on top of cons cells, you can
treat @code{list-alist} in the example above as a cons cell alist, where
the value type is a list with a single element containing the real
value.
@example
@smallexample
(defcustom list-alist '(("foo" 1) ("bar" 2) ("baz" 3))
"Each element is a list of the form (KEY VALUE)."
:type '(alist :value-type (group integer)))
@end example
@end smallexample
The @code{group} widget is used here instead of @code{list} only because
the formatting is better suited for the purpose.
@ -477,7 +486,7 @@ the formatting is better suited for the purpose.
Similarily, you can have alists with more values associated with each
key, using variations of this trick:
@example
@smallexample
(defcustom person-data '(("brian" 50 t)
("dorith" 55 nil)
("ken" 52 t))
@ -489,16 +498,16 @@ key, using variations of this trick:
("ken" "cat"))
"Alist where the KEY is a person, and the VALUE is a list of pets."
:type '(alist :value-type (repeat string)))
@end example
@end smallexample
@item plist
The @code{plist} custom type is similar to the @code{alist} (see above),
except that the information is stored as a property list, i.e. a list of
this form:
@example
@smallexample
(@var{key} @var{value} @var{key} @var{value} @var{key} @var{value} @dots{})
@end example
@end smallexample
The default @code{:key-type} for @code{plist} is @code{symbol},
rather than @code{sexp}.

47
lispref/debugging.texi
View file

@ -510,9 +510,9 @@ debugger.
@defvar debugger
The value of this variable is the function to call to invoke the
debugger. Its value must be a function of any number of arguments (or,
more typically, the name of a function). Presumably this function will
enter some kind of debugger. The default value of the variable is
debugger. Its value must be a function of any number of arguments, or,
more typically, the name of a function. This function should invoke
some kind of debugger. The default value of the variable is
@code{debug}.
The first argument that Lisp hands to the function indicates why it
@ -531,11 +531,13 @@ value is always @code{nil}.
In the following example, a Lisp expression calls @code{backtrace}
explicitly. This prints the backtrace to the stream
@code{standard-output}: in this case, to the buffer
@samp{backtrace-output}. Each line of the backtrace represents one
function call. The line shows the values of the function's arguments if
they are all known. If they are still being computed, the line says so.
The arguments of special forms are elided.
@code{standard-output}, which, in this case, is the buffer
@samp{backtrace-output}.
Each line of the backtrace represents one function call. The line shows
the values of the function's arguments if they are all known; if they
are still being computed, the line says so. The arguments of special
forms are elided.
@smallexample
@group
@ -620,9 +622,9 @@ bound to @code{nil}. The debugger can set this variable to leave
information for future debugger invocations during the same command
invocation.
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.
The advantage 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
@defun backtrace-frame frame-number
@ -630,11 +632,11 @@ The function @code{backtrace-frame} is intended for use in Lisp
debuggers. It returns information about what computation is happening
in the stack frame @var{frame-number} levels down.
If that frame has not evaluated the arguments yet (or is a special
form), the value is @code{(nil @var{function} @var{arg-forms}@dots{})}.
If that frame has not evaluated the arguments yet, or is a special
form, the value is @code{(nil @var{function} @var{arg-forms}@dots{})}.
If that frame has evaluated its arguments and called its function
already, the value is @code{(t @var{function}
already, the return value is @code{(t @var{function}
@var{arg-values}@dots{})}.
In the return value, @var{function} is whatever was supplied as the
@ -679,12 +681,9 @@ find the mismatch.)
@subsection Excess Open Parentheses
The first step is to find the defun that is unbalanced. If there is
an excess open parenthesis, the way to do this is to insert a
close parenthesis at the end of the file and type @kbd{C-M-b}
(@code{backward-sexp}). This will move you to the beginning of the
defun that is unbalanced. (Then type @kbd{C-@key{SPC} C-_ C-u
C-@key{SPC}} to set the mark there, undo the insertion of the
close parenthesis, and finally return to the mark.)
an excess open parenthesis, the way to do this is to go to the end of
the file and type @kbd{C-u C-M-u}. This will move you to the beginning
of the defun that is unbalanced.
The next step is to determine precisely what is wrong. There is no
way to be sure of this except by studying the program, but often the
@ -715,11 +714,9 @@ anything.
@node Excess Close
@subsection Excess Close Parentheses
To deal with an excess close parenthesis, first insert an open
parenthesis at the beginning of the file, back up over it, and type
@kbd{C-M-f} to find the end of the unbalanced defun. (Then type
@kbd{C-@key{SPC} C-_ C-u C-@key{SPC}} to set the mark there, undo the
insertion of the open parenthesis, and finally return to the mark.)
To deal with an excess close parenthesis, first go to the beginning of
the file, then type @kbd{C-u -1 C-M-u} to find the end of the unbalanced
defun.
Then find the actual matching close parenthesis by typing @kbd{C-M-f}
at the beginning of that defun. This will leave you somewhere short of

1608
lispref/display.texi
View file

File diff suppressed because it is too large Load diff

163
lispref/edebug.texi
View file

@ -66,9 +66,9 @@ enable you to use it.
* Jumping:: Commands to jump to a specified place.
* Misc: Edebug Misc. Miscellaneous commands.
* Breakpoints:: Setting breakpoints to make the program stop.
* Trapping Errors:: trapping errors with Edebug.
* Trapping Errors:: Trapping errors with Edebug.
* Views: Edebug Views. Views inside and outside of Edebug.
* Eval: Edebug Eval. Evaluating expressions within Edebug.
* Eval: Edebug Eval. Evaluating expressions within Edebug.
* Eval List:: Expressions whose values are displayed
each time you enter Edebug.
* Printing in Edebug:: Customization of printing.
@ -89,23 +89,23 @@ first move point into the definition of a function or macro and then do
@ref{Instrumenting}, for alternative ways to instrument code.
Once a function is instrumented, any call to the function activates
Edebug. Activating Edebug may stop execution and let you step through
the function, or it may update the display and continue execution while
checking for debugging commands, depending on which Edebug execution
mode you have selected. The default execution mode is step, which does
stop execution. @xref{Edebug Execution Modes}.
Edebug. Depending on which Edebug execution mode you have selected,
activating Edebug may stop execution and let you step through the
function, or it may update the display and continue execution while
checking for debugging commands. The default execution mode is step,
which stops execution. @xref{Edebug Execution Modes}.
Within Edebug, you normally view an Emacs buffer showing the source of
the Lisp code you are debugging. This is referred to as the @dfn{source
code buffer}. This buffer is temporarily read-only.
code buffer}, and is is temporarily read-only.
An arrow at the left margin indicates the line where the function is
executing. Point initially shows where within the line the function is
executing, but this ceases to be true if you move point yourself.
If you instrument the definition of @code{fac} (shown below) and then
execute @code{(fac 3)}, here is what you normally see. Point is at the
open-parenthesis before @code{if}.
execute @code{(fac 3)}, here is what you would normally see. Point is
at the open-parenthesis before @code{if}.
@example
(defun fac (n)
@ -118,7 +118,7 @@ open-parenthesis before @code{if}.
The places within a function where Edebug can stop execution are called
@dfn{stop points}. These occur both before and after each subexpression
that is a list, and also after each variable reference.
Here we show with periods the stop points found in the function
Here we use periods to show the stop points in the function
@code{fac}:
@example
@ -163,7 +163,7 @@ into it, to invoke Edebug at the proper places.
argument on a definition, it instruments the definition before
evaluating it. (The source code itself is not modified.) If the
variable @code{edebug-all-defs} is non-@code{nil}, that inverts the
meaning of the prefix argument: then @kbd{C-M-x} instruments the
meaning of the prefix argument: in this case, @kbd{C-M-x} instruments the
definition @emph{unless} it has a prefix argument. The default value of
@code{edebug-all-defs} is @code{nil}. The command @kbd{M-x
edebug-all-defs} toggles the value of the variable
@ -188,10 +188,11 @@ instrument any top-level form regardless of the values of
(@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
source for that function; after loading Edebug, @code{eval-region}
records the position of every definition it evaluates, even if not
instrumenting it. See also the @kbd{i} command (@pxref{Jumping}), which
steps into the call after instrumenting the function.
source for that function; for this reading, after loading Edebug,
@code{eval-region} records the position of every definition it
evaluates, even if not instrumenting it. See also the @kbd{i} command
(@pxref{Jumping}), which steps into the call after instrumenting the
function.
@cindex special forms (Edebug)
@cindex interactive commands (Edebug)
@ -201,15 +202,16 @@ steps into the call after instrumenting the function.
@pindex cl-specs.el
Edebug knows how to instrument all the standard special forms,
@code{interactive} forms with an expression argument, anonymous lambda
expressions, and other defining forms. Edebug cannot know what a
user-defined macro will do with the arguments of a macro call, so you
must tell it; see @ref{Instrumenting Macro Calls}, for details.
expressions, and other defining forms. However, Edebug cannot determine
on its own what a user-defined macro will do with the arguments of a
macro call, so you must provide that information; see @ref{Instrumenting
Macro Calls}, for details.
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
@code{nil}. You can use this to load Edebug specifications
(@pxref{Instrumenting Macro Calls}) associated with a package you are
using, but actually load them only if you use Edebug.
using, but only when you use Edebug.
@findex eval-expression @r{(Edebug)}
To remove instrumentation from a definition, simply re-evaluate its
@ -238,12 +240,12 @@ before it stops.
Normally, you specify the Edebug execution mode by typing a command to
continue the program in a certain mode. Here is a table of these
commands. All except for @kbd{S} resume execution of the program, at
commands; all except for @kbd{S} resume execution of the program, at
least for a certain distance.
@table @kbd
@item S
Stop: don't execute any more of the program for now, just wait for more
Stop: don't execute any more of the program, but wait for more
Edebug commands (@code{edebug-stop}).
@item @key{SPC}
@ -296,7 +298,7 @@ Keyboard macros containing the commands in this section do not
completely work: exiting from Edebug, to resume the program, loses track
of the keyboard macro. This is not easy to fix. Also, defining or
executing a keyboard macro outside of Edebug does not affect commands
inside Edebug. This is usually an advantage. But see the
inside Edebug. This is usually an advantage. See also the
@code{edebug-continue-kbd-macro} option (@pxref{Edebug Options}).
When you enter a new Edebug level, the initial execution mode comes from
@ -316,8 +318,8 @@ breakpoint reached before the intended stop point will also stop
execution. @xref{Breakpoints}, for the details on breakpoints.
These commands may fail to work as expected in case of nonlocal exit,
because a nonlocal exit can bypass the temporary breakpoint where you
expected the program to stop.
as that can bypass the temporary breakpoint where you expected the
program to stop.
@table @kbd
@item h
@ -348,13 +350,13 @@ With a prefix argument @var{n}, the temporary breakpoint is placed
more elements, then the place to stop is after the containing
expression.
Be careful that the position @kbd{C-M-f} finds is a place that the
program will really get to; this may not be true in a
@code{cond}, for example.
You must check that the position @kbd{C-M-f} finds is a place that the
program will really get to. In @code{cond}, for example, this may not
be true.
The @kbd{f} command does @code{forward-sexp} starting at point, rather
than at the stop point, for flexibility. If you want to execute one
expression @emph{from the current stop point}, type @kbd{w} first, to
For flexibility, the @kbd{f} command does @code{forward-sexp} starting
at point, rather than at the stop point. If you want to execute one
expression @emph{from the current stop point}, first type @kbd{w}, to
move point there, and then type @kbd{f}.
The @kbd{o} command continues ``out of'' an expression. It places a
@ -397,7 +399,7 @@ activity. However, instrumented code protected with
debugging.
@item Q
Like @kbd{q} but don't stop even for protected code
Like @kbd{q}, but don't stop even for protected code
(@code{top-level-nonstop}).
@item r
@ -415,22 +417,21 @@ The backtrace buffer is killed automatically when you continue
execution.
@end table
From the Edebug recursive edit, you may invoke commands that activate
Edebug again recursively. Any time Edebug is active, you can quit to
the top level with @kbd{q} or abort one recursive edit level with
@kbd{C-]}. You can display a backtrace of all the
pending evaluations with @kbd{d}.
You can invoke commands from Edebug that activate Edebug again
recursively. Whenever Edebug is active, you can quit to the top level
with @kbd{q} or abort one recursive edit level with @kbd{C-]}. You can
display a backtrace of all the pending evaluations with @kbd{d}.
@node Breakpoints
@subsection Breakpoints
@cindex breakpoints
Edebug's step mode stops execution at the next stop point reached.
Edebug's step mode stops execution when the next stop point is reached.
There are three other ways to stop Edebug execution once it has started:
breakpoints, the global break condition, and source breakpoints.
While using Edebug, you can specify @dfn{breakpoints} in the program you
are testing: points where execution should stop. You can set a
are testing: these are places where execution should stop. You can set a
breakpoint at any stop point, as defined in @ref{Using Edebug}. For
setting and unsetting breakpoints, the stop point that is affected is
the first one at or after point in the source code buffer. Here are the
@ -440,8 +441,8 @@ Edebug commands for breakpoints:
@item b
Set a breakpoint at the stop point at or after point
(@code{edebug-set-breakpoint}). If you use a prefix argument, the
breakpoint is temporary (it turns off the first time it stops the
program).
breakpoint is temporary---it turns off the first time it stops the
program.
@item u
Unset the breakpoint (if any) at the stop point at or after
@ -463,7 +464,8 @@ with @kbd{u}. First move point to the Edebug stop point of your choice,
then type @kbd{b} or @kbd{u} to set or unset a breakpoint there.
Unsetting a breakpoint where none has been set has no effect.
Re-evaluating or reinstrumenting a definition forgets all its breakpoints.
Re-evaluating or reinstrumenting a definition removes all of its
previous breakpoints.
A @dfn{conditional breakpoint} tests a condition each time the program
gets there. Any errors that occur as a result of evaluating the
@ -478,7 +480,7 @@ You can make a conditional or unconditional breakpoint
breakpoint. When a temporary breakpoint stops the program, it is
automatically unset.
Edebug always stops or pauses at a breakpoint except when the Edebug
Edebug always stops or pauses at a breakpoint, except when the Edebug
mode is Go-nonstop. In that mode, it ignores breakpoints entirely.
To find out where your breakpoints are, use the @kbd{B} command, which
@ -500,7 +502,7 @@ point in the buffer.
@cindex global break condition
A @dfn{global break condition} stops execution when a specified
condition is satisfied, no matter where that may occur. Edebug
evaluates the global break condition at every stop point. If it
evaluates the global break condition at every stop point; if it
evaluates to a non-@code{nil} value, then execution stops or pauses
depending on the execution mode, as if a breakpoint had been hit. If
evaluating the condition gets an error, execution does not stop.
@ -520,11 +522,12 @@ should reset the condition to @code{nil} when not using it.
@findex edebug
@cindex source breakpoints
All breakpoints in a definition are forgotten each time you
reinstrument it. To make a breakpoint that won't be forgotten, you can
write a @dfn{source breakpoint}, which is simply a call to the function
@code{edebug} in your source code. You can, of course, make such a call
conditional. For example, in the @code{fac} function, insert the first
line as shown below to stop when the argument reaches zero:
reinstrument it. If you wish to make a breakpoint that won't be
forgotten, you can write a @dfn{source breakpoint}, which is simply a
call to the function @code{edebug} in your source code. You can, of
course, make such a call conditional. For example, in the @code{fac}
function, you can insert the first line as shown below, to stop when the
argument reaches zero:
@example
(defun fac (n)
@ -553,10 +556,10 @@ and @code{edebug-on-quit}; see @ref{Edebug Options}.
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
function which was not instrumented, and within which the error actually
occurred. For an unbound variable error, the last known stop point
might be quite distant from the offending variable reference. In that
case you might want to display a full backtrace (@pxref{Edebug Misc}).
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
@ -616,12 +619,12 @@ open.
@node Edebug Eval
@subsection Evaluation
While within Edebug, you can evaluate expressions ``as if'' Edebug were
not running. Edebug tries to be invisible to the expression's
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
saves and restores. @xref{The Outside Context}, for details on this
process.
effects will work as expected, except for changes to data that Edebug
explicitly saves and restores. @xref{The Outside Context}, for details
on this process.
@table @kbd
@item e @var{exp} @key{RET}
@ -739,9 +742,9 @@ eval-last-sexp
To delete a group, move point into it and type @kbd{C-c C-d}, or simply
delete the text for the group and update the evaluation list with
@kbd{C-c C-u}. To add a new expression to the evaluation list, insert
the expression at a suitable place, and insert a new comment line. (You
need not insert dashes in the comment line---its contents don't matter.)
Then type @kbd{C-c C-u}.
the expression at a suitable place, insert a new comment line, then type
@kbd{C-c C-u}. You need not insert dashes in the comment line---its
contents don't matter.
After selecting @samp{*edebug*}, you can return to the source code
buffer with @kbd{C-c C-w}. The @samp{*edebug*} buffer is killed when
@ -764,22 +767,18 @@ 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}.
If non-@code{nil}, Edebug binds @code{print-length} to this value while
printing results. The default value is @code{50}.
@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}.
If non-@code{nil}, Edebug binds @code{print-level} to this value while
printing results. 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.
To load @file{cust-print} and activate custom printing only for
Edebug, simply use the command @kbd{M-x edebug-install-custom-print}.
To restore the standard print functions, use @kbd{M-x
edebug-uninstall-custom-print}.
elements more informatively by binding @code{print-circle}
to a non-@code{nil} value.
Here is an example of code that creates a circular structure:
@ -796,8 +795,8 @@ 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}.
If non-@code{nil}, Edebug binds @code{print-circle} to this value while
printing results. The default value is @code{nil}.
@end defopt
Other programs can also use custom printing; see @file{cust-print.el}
@ -816,9 +815,9 @@ trace recording, set @code{edebug-trace} to a non-@code{nil} value.
mode (@pxref{Edebug Execution Modes}).
When trace recording is enabled, each function entry and exit adds
lines to the trace buffer. A function entry record looks like
@samp{::::@{} followed by the function name and argument values. A
function exit record looks like @samp{::::@}} followed by the function
lines to the trace buffer. A function entry record consists of
@samp{::::@{}, followed by the function name and argument values. A
function exit record consists of @samp{::::@}}, followed by the function
name and result of the function.
The number of @samp{:}s in an entry shows its recursion depth. You
@ -834,7 +833,7 @@ redefining the functions @code{edebug-print-trace-before} and
@defmac edebug-tracing string body@dots{}
This macro requests additional trace information around the execution
of the @var{body} forms. The argument @var{string} specifies text
to put in the trace buffer. All the arguments are evaluated.
to put in the trace buffer. All the arguments are evaluated, and
@code{edebug-tracing} returns the value of the last form in @var{body}.
@end defmac
@ -964,15 +963,15 @@ the current window configuration from ``outside'' Edebug
the program), it restores the previous window configuration.
Emacs redisplays only when it pauses. Usually, when you continue
execution, the program comes back into Edebug at a breakpoint or after
stepping without pausing or reading input in between. In such cases,
execution, the program re-enters Edebug at a breakpoint or after
stepping, without pausing or reading input in between. In such cases,
Emacs never gets a chance to redisplay the ``outside'' configuration.
What you see is the same window configuration as the last time Edebug
was active, with no interruption.
Consequently, what you see is the same window configuration as the last
time Edebug was active, with no interruption.
Entry to Edebug for displaying something also saves and restores the
following data, but some of these are deliberately not restored if an
error or quit signal occurs.
following data (though some of them are deliberately not restored if an
error or quit signal occurs).
@itemize @bullet
@item

24
lispref/elisp.texi
View file

@ -12,8 +12,8 @@
@smallbook
@ifinfo
This Info file contains edition 2.5.1 of the GNU Emacs Lisp
Reference Manual, corresponding to Emacs version 20.4.
This Info file contains edition 2.6 of the GNU Emacs Lisp
Reference Manual, corresponding to Emacs version 21.1.
@c Please REMEMBER to update edition number in *four* places in this file
@c and also in *one* place in intro.texi
@ -75,7 +75,7 @@ instead of in the original English.
@subtitle For Emacs Version 20.4
@c The edition number appears in several places in this file
@c and also in the file intro.texi.
@subtitle Revision 2.5.1, January 1999
@subtitle Revision 2.6, September 1999
@author by Bil Lewis, Dan LaLiberte, Richard Stallman
@author and the GNU Manual Group
@ -85,11 +85,11 @@ Copyright @copyright{} 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1998, 1999
Free Software Foundation, Inc.
@sp 2
Edition 2.5.1 @*
Revised for Emacs Version 20.4,@*
January 1999.@*
Edition 2.6 @*
Revised for Emacs Version 21.1,@*
September 1999.@*
@sp 2
ISBN 1-882114-72-8
ISBN 1-882114-73-6
@sp 2
Published by the Free Software Foundation @*
@ -120,8 +120,8 @@ Cover art by Etienne Suvasa.
@node Top, Copying, (dir), (dir)
@ifinfo
This Info file contains edition 2.5.1 of the GNU Emacs Lisp
Reference Manual, corresponding to GNU Emacs version 20.4.
This Info file contains edition 2.6 of the GNU Emacs Lisp
Reference Manual, corresponding to GNU Emacs version 21.1.
@end ifinfo
@menu
@ -136,6 +136,7 @@ Reference Manual, corresponding to GNU Emacs version 20.4.
* Sequences Arrays Vectors:: Lists, strings and vectors are called sequences.
Certain functions act on any kind of sequence.
The description of vectors is here as well.
* Hash Tables:: Very fast lookup-tables.
* Symbols:: Symbols represent names, uniquely.
* Evaluation:: How Lisp expressions are evaluated.
@ -867,10 +868,10 @@ Operating System Interface
Starting Up Emacs
* Start-up Summary:: Sequence of actions Emacs performs at start-up.
* Startup Summary:: Sequence of actions Emacs performs at start-up.
* Init File:: Details on reading the init file (@file{.emacs}).
* Terminal-Specific:: How the terminal-specific Lisp file is read.
* Command Line Arguments:: How command line arguments are processed,
* Command-Line Arguments:: How command line arguments are processed,
and how you can customize them.
Getting out of Emacs
@ -914,6 +915,7 @@ Object Internals
@include lists.texi
@include sequences.texi
@include hash.texi
@include symbols.texi
@include eval.texi

8
lispref/errors.texi
View file

@ -64,12 +64,12 @@ See @code{/} and @code{%} in @ref{Numbers}.
@item end-of-file
@code{"End of file during parsing"}@*
Note that this is not a @code{file-error}
Note that this is not a subcategory of @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}.@*
This is a subcategory of @code{file-error}.@*
@xref{Writing to Files}.
@item file-date-error
@ -84,11 +84,11 @@ condition @code{file-error} is present.@*
@xref{Files}.
@item file-locked
This is a @code{file-error}.@*
This is a subcategory of @code{file-error}.@*
@xref{File Locks}.
@item file-supersession
This is a @code{file-error}.@*
This is a subcategory of @code{file-error}.@*
@xref{Modification Time}.
@item invalid-function

218
lispref/files.texi
View file

@ -126,7 +126,7 @@ the user whether to reread the changed file. If the user says
This function displays warning or advisory messages in various peculiar
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
@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
@ -260,7 +260,7 @@ and by the default revert function (@pxref{Reverting}).
If reading the file got an error because the file does not exist, but
its directory does exist, the caller should pass a non-@code{nil} value
for @var{error}. In that case, @code{after-find-file} issues a warning:
@samp{(New File)}. For more serious errors, the caller should usually not
@samp{(New file)}. For more serious errors, the caller should usually not
call @code{after-find-file}.
If @var{warn} is non-@code{nil}, then this function issues a warning
@ -312,7 +312,7 @@ the user.
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}
buffer-local value of @code{buffer-offer-save}. (A user who says yes to
buffer-local value of @code{buffer-offer-save}. (A user who says @samp{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.
@ -447,7 +447,9 @@ The function @code{insert-file-contents} checks the file contents
against the defined file formats, and converts the file contents if
appropriate. @xref{Format Conversion}. It also calls the functions in
the list @code{after-insert-file-functions}; see @ref{Saving
Properties}.
Properties}. Normally, one of the functions in the
@code{after-insert-file-functions} list determines the coding system
(@pxref{Coding Systems}) used for decoding the file's contents.
If @var{visit} is non-@code{nil}, this function additionally marks the
buffer as unmodified and sets up various fields in the buffer so that it
@ -510,19 +512,29 @@ An error is signaled if @var{filename} specifies a nonwritable file,
or a nonexistent file in a directory where files cannot be created.
@end deffn
@deffn Command write-region start end filename &optional append visit confirm
@deffn Command write-region start end filename &optional append visit mustbenew
This function writes the region delimited by @var{start} and @var{end}
in the current buffer into the file specified by @var{filename}.
@c Emacs 19 feature
If @var{start} is a string, then @code{write-region} writes or appends
that string, rather than text from the buffer.
that string, rather than text from the buffer. @var{end} is ignored in
this case.
If @var{append} is non-@code{nil}, then the specified text is appended
to the existing file contents (if any).
If @var{confirm} is non-@code{nil}, then @code{write-region} asks
If @var{mustbenew} is non-@code{nil}, then @code{write-region} asks
for confirmation if @var{filename} names an existing file.
Starting in Emacs 21, if @var{mustbenew} is the symbol @code{excl},
then @code{write-region} does not ask for confirmation, but instead
it signals an error @code{file-already-exists} if the file already
exists.
The test for an existing file, when @var{mustbenew} is @code{excl}, uses
a special system feature. At least for files on a local disk, there is
no chance that some other program could create a file of the same name
before Emacs does, without Emacs's noticing.
If @var{visit} is @code{t}, then Emacs establishes an association
between the buffer and the file: the buffer is then visiting that file.
@ -615,6 +627,10 @@ the file should not be locked, so this function does nothing. It also
does nothing if the current buffer is not visiting a file.
@end defun
File locking is not supported on some systems. On systems that do not
support it, the functions @code{lock-buffer}, @code{unlock-buffer} and
@code{file-locked-p} do nothing and return @code{nil}.
@defun ask-user-about-lock file other-user
This function is called when the user tries to modify @var{file}, but it
is locked by another user named @var{other-user}. The default
@ -710,10 +726,10 @@ and you can read it. It returns @code{nil} otherwise.
@c Emacs 19 feature
@defun file-executable-p filename
This function returns @code{t} if a file named @var{filename} exists and
you can execute it. It returns @code{nil} otherwise. If the file is a
directory, execute permission means you can check the existence and
attributes of files inside the directory, and open those files if their
modes permit.
you can execute it. It returns @code{nil} otherwise. On Unix, if the
file is a directory, execute permission means you can check the
existence and attributes of files inside the directory, and open those
files if their modes permit.
@end defun
@defun file-writable-p filename
@ -1081,7 +1097,8 @@ was last modified on Aug 19 00:09.
last had its inode changed on Aug 19 00:09.
@item 14906
is 14906 characters long.
is 14906 bytes long. (It may not contain 14906 characters, though,
if some of the bytes belong to multibyte sequences.)
@item "-rw-rw-rw-"
has a mode of read and write access for the owner, group, and world.
@ -1186,7 +1203,8 @@ contents of @file{foo3} are lost.
@end example
This function is meaningless on operating systems where multiple names
for one file are not allowed.
for one file are not allowed. Some systems implement multiple names
by copying the file instead.
See also @code{file-nlinks} in @ref{File Attributes}.
@end defun
@ -1241,6 +1259,9 @@ This command makes a symbolic link to @var{filename}, named
In an interactive call, this function prompts for @var{filename} and
@var{newname} in the minibuffer; also, it requests confirmation if
@var{newname} already exists.
This function is not available on systems that don't support symbolic
links.
@end deffn
@defun define-logical-name varname string
@ -1275,9 +1296,13 @@ This function returns the current default protection value.
@cindex MS-DOS and file modes
@cindex file modes and MS-DOS
On MS-DOS, there is no such thing as an ``executable'' file mode bit.
So Emacs considers a file executable if its name ends in @samp{.com},
@samp{.bat} or @samp{.exe}. This is reflected in the values returned
by @code{file-modes} and @code{file-attributes}.
So Emacs considers a file executable if its name ends in one of the
standard executable extensions, such as @file{.com}, @file{.bat},
@file{.exe}, and some others. Files that begin with the Unix-standard
@samp{#!} signature, such as shell and Perl scripts, are also considered
as executable files. This is reflected in the values returned by
@code{file-modes} and @code{file-attributes}. Directories are also
reported with executable bit set, for compatibility with Unix.
@node File Names
@section File Names
@ -1327,22 +1352,22 @@ parts: the @dfn{directory name} part, and the @dfn{nondirectory} part
(or @dfn{file name within the directory}). Either part may be empty.
Concatenating these two parts reproduces the original file name.
On Unix, the directory part is everything up to and including the last
slash; the nondirectory part is the rest. The rules in VMS syntax are
complicated.
On most systems, the directory part is everything up to and including
the last slash; the nondirectory part is the rest. The rules in VMS
syntax are complicated.
For some purposes, the nondirectory part is further subdivided into
the name proper and the @dfn{version number}. On Unix, only backup
files have version numbers in their names. On VMS, every file has a
version number, but most of the time the file name actually used in
Emacs omits the version number, so that version numbers in Emacs are
the name proper and the @dfn{version number}. On most systems, only
backup files have version numbers in their names. On VMS, every file
has a version number, but most of the time the file name actually used
in Emacs omits the version number, so that version numbers in Emacs are
found mostly in directory lists.
@defun file-name-directory filename
This function returns the directory part of @var{filename} (or
@code{nil} if @var{filename} does not include a directory part). On
Unix, the function returns a string ending in a slash. On VMS, it
returns a string ending in one of the three characters @samp{:},
most systems, the function returns a string ending in a slash. On VMS,
it returns a string ending in one of the three characters @samp{:},
@samp{]}, or @samp{>}.
@example
@ -1429,7 +1454,7 @@ The extension, in a file name, is the part that starts with the last
kind of file, and it has a file name, which is related to the directory
name but not identical to it. (This is not quite the same as the usual
Unix terminology.) These two different names for the same entity are
related by a syntactic transformation. On Unix, this is simple: a
related by a syntactic transformation. On most systems, this is simple: a
directory name ends in a slash, whereas the directory's name as a file
lacks that slash. On VMS, the relationship is more complicated.
@ -1444,9 +1469,9 @@ such as @samp{$HOME}, and the constructs @samp{~}, and @samp{..}.
@defun file-name-as-directory filename
This function returns a string representing @var{filename} in a form
that the operating system will interpret as the name of a directory. In
Unix, this means appending a slash to the string (if it does not already
end in one). On VMS, the function converts a string of the form
that the operating system will interpret as the name of a directory. On
most systems, this means appending a slash to the string (if it does not
already end in one). On VMS, the function converts a string of the form
@file{[X]Y.DIR.1} to the form @file{[X.Y]}.
@example
@ -1459,9 +1484,9 @@ end in one). On VMS, the function converts a string of the form
@defun directory-file-name dirname
This function returns a string representing @var{dirname} in a form that
the operating system will interpret as the name of a file. On Unix,
this means removing the final slash from the string. On VMS, the
function converts a string of the form @file{[X.Y]} to
the operating system will interpret as the name of a file. On most
systems, this means removing the final slash from the string. On VMS,
the function converts a string of the form @file{[X.Y]} to
@file{[X]Y.DIR.1}.
@example
@ -1522,8 +1547,10 @@ starting from the root of the tree; then it is called an @dfn{absolute}
file name. Or it can specify the position of the file in the tree
relative to a default directory; then it is called a @dfn{relative}
file name. On Unix, an absolute file name starts with a slash or a
tilde (@samp{~}), and a relative one does not. The rules on VMS are
complicated.
tilde (@samp{~}), and a relative one does not. On MS-DOS and
MS-Windows, an absolute file name starts with a slash or a backslash, or
with a drive specification @samp{@var{x}:/}, where @var{x} is the
@dfn{drive letter}. The rules on VMS are complicated.
@defun file-name-absolute-p filename
This function returns @code{t} if file @var{filename} is an absolute
@ -1625,7 +1652,7 @@ 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}.
On Unix systems, the value is always a string ending with a slash.
Aside from VMS, the value is always a string ending with a slash.
@example
@group
@ -1680,7 +1707,54 @@ on VMS except discard superfluous initial components as shown above.
@subsection Generating Unique File Names
Some programs need to write temporary files. Here is the usual way to
construct a name for such a file:
construct a name for such a file, starting in Emacs 21:
@example
(make-temp-file @var{name-of-application})
@end example
@noindent
The job of @code{make-temp-file} is to prevent two different users or
two different jobs from trying to use the exact same file name.
@defun make-temp-file prefix &optional dir-flag
@tindex make-temp-file
This function creates a temporary file and returns its name.
The name starts with @var{prefix}; it also contains a number that is
different in each Emacs job. If @var{prefix} is a relative file name,
it is expanded against @code{temporary-file-directory}.
@example
@group
(make-temp-file "foo")
@result{} "/tmp/foo232J6v"
@end group
@end example
When @code{make-temp-file} returns, the file has been created and is
empty. At that point, you should write the intended contents into the
file.
If @var{dir-flag} is non-@code{nil}, @code{make-temp-file} creates
an empty directory instead of an empty file.
To prevent conflicts among different libraries running in the same
Emacs, each Lisp program that uses @code{make-temp-file} should have its
own @var{prefix}. The number added to the end of @var{prefix}
distinguishes between the same application running in different Emacs
jobs. Additional added characters permit a large number of distinct
names even in one Emacs job.
@end defun
The default directory for temporary files is controlled by the
variable @code{temporary-file-directory}. This variable gives the user
a uniform way to specify the directory for all temporary files. Some
programs use @code{small-temporary-file-directory} instead, if that is
non-@code{nil}. To use it, you should expand the prefix against
the proper directory before calling @code{make-temp-file}.
In older Emacs versions where @code{make-temp-file} does not exist,
you should use @code{make-temp-name} instead:
@example
(make-temp-name
@ -1688,37 +1762,19 @@ construct a name for such a file:
temporary-file-directory))
@end example
@noindent
The job of @code{make-temp-name} is to prevent two different users or
two different jobs from trying to use the exact same file name. This
example uses the variable @code{temporary-file-directory} to decide
where to put the temporary file. All Emacs Lisp programs should
use @code{temporary-file-directory} for this purpose, to give the user
a uniform way to specify the directory for all temporary files.
@defun make-temp-name string
This function generates a string that can be used as a unique file name.
The name starts with @var{string}, and contains a number that is
different in each Emacs job.
@example
@group
(make-temp-name "/tmp/foo")
@result{} "/tmp/foo232J6v"
@end group
@end example
To prevent conflicts among different libraries running in the same
Emacs, each Lisp program that uses @code{make-temp-name} should have its
own @var{string}. The number added to the end of @var{string}
distinguishes between the same application running in different Emacs
jobs. Additional added characters permit a large number of distinct
names even in one Emacs job.
different in each Emacs job. It is like @code{make-temp-file} except
that it just constructs a name, and does not create a file. On MS-DOS,
the @var{string} prefix can be truncated to fit into the 8+3 file-name
limits.
@end defun
@defvar temporary-file-directory
@cindex @code{TMPDIR} environment variable.
@cindex @code{TMP} environment variable.
@cindex @code{TMPDIR} environment variable
@cindex @code{TMP} environment variable
@cindex @code{TEMP} environment variable
This variable specifies the directory name for creating temporary files.
Its value should be a directory name (@pxref{Directory Names}), but it
is good for Lisp programs to cope if the value is a directory's file
@ -1726,12 +1782,31 @@ name instead. Using the value as the second argument to
@code{expand-file-name} is a good way to achieve that.
The default value is determined in a reasonable way for your operating
system; on GNU and Unix systems it is based on the @code{TMP} and
@code{TMPDIR} environment variables.
system; it is based on the @code{TMPDIR}, @code{TMP} and @code{TEMP}
environment variables, with a fall-back to a system-dependent name if
none of these variables is defined.
Even if you do not use @code{make-temp-name} to choose the temporary
file's name, you should still use this variable to decide which
directory to put the file in.
directory to put the file in. However, if you expect the file to be
small, you should use @code{small-temporary-file-directory} first if
that is non-@code{nil}.
@end defvar
@tindex small-temporary-file-directory
@defvar small-temporary-file-directory
This variable (new in Emacs 21) specifies the directory name for
creating certain temporary files, which are likely to be small.
If you want to write a temporary file which is likely to be small, you
should compute the directory like this:
@example
(make-temp-file
(expand-file-name @var{prefix}
(or small-temporary-file-directory
temporary-file-directory)))
@end example
@end defvar
@node File Name Completion
@ -1953,15 +2028,20 @@ not contain @samp{-d}. (The @samp{-d} option to @code{ls} says to
describe a directory itself as a file, rather than showing its
contents.)
This function works by running a directory listing program whose name is
in the variable @code{insert-directory-program}. If @var{wildcard} is
non-@code{nil}, it also runs the shell specified by
On most systems, this function works by running a directory listing
program whose name is in the variable @code{insert-directory-program}.
If @var{wildcard} is non-@code{nil}, it also runs the shell specified by
@code{shell-file-name}, to expand the wildcards.
MS-DOS and MS-Windows systems usually lack the standard Unix program
@code{ls}, so this function emulates the standard Unix program @code{ls}
with Lisp code.
@end defun
@defvar insert-directory-program
This variable's value is the program to run to generate a directory listing
for the function @code{insert-directory}.
for the function @code{insert-directory}. It is ignored on systems
which generate the listing with Lisp code.
@end defvar
@node Create/Delete Dirs
@ -2070,6 +2150,7 @@ Here are the operations that a magic file name handler gets to handle:
@end ifinfo
@iftex
@noindent
@flushleft
@code{add-name-to-file}, @code{copy-file}, @code{delete-directory},
@code{delete-file},
@code{diff-latest-backup-file},
@ -2103,6 +2184,7 @@ Here are the operations that a magic file name handler gets to handle:
@code{vc-regis@discretionary{}{}{}tered},
@code{verify-visited-file-modtime},
@code{write-region}.
@end flushleft
@end iftex
Handlers for @code{insert-file-contents} typically need to clear the

340
lispref/frames.texi
View file

@ -24,8 +24,22 @@ 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
@code{nil} otherwise.
This predicate returns a non-@code{nil} value if @var{object} is a
frame, and @code{nil} otherwise. For a frame, the value indicates which
kind of display the frame uses:
@table @code
@item x
The frame is displayed in an X window.
@item t
A terminal frame on a character display.
@item mac
The frame is displayed on a Macintosh.
@item w32
The frame is displayed on MS-Windows 9X/NT.
@item pc
The frame is displayed on an MS-DOS terminal.
@end table
@end defun
@menu
@ -49,10 +63,8 @@ This predicate returns @code{t} if @var{object} is a frame, and
* Dialog Boxes:: Displaying a box to ask yes or no.
* Pointer Shapes:: Specifying the shape of the mouse pointer.
* Window System Selections:: Transferring text to and from other X clients.
* Font Names:: Looking up font names.
* Fontsets:: A fontset is a collection of fonts
for displaying various character sets.
* Color Names:: Getting the definitions of color names.
* Text Terminal Colors:: Defining colors for text-only terminals.
* Resources:: Getting resource values from the server.
* Server Data:: Getting info about the X server.
@end menu
@ -86,8 +98,8 @@ A normal hook run by @code{make-frame} before it actually creates the
frame.
@end defvar
@defvar after-make-frame-hook
@tindex after-make-frame-hook
@defvar after-make-frame-functions
@tindex after-make-frame-functions
An abnormal hook run by @code{make-frame} after it creates the frame.
Each function in @code{after-make-frame-hook} receives one argument, the
frame just created.
@ -163,14 +175,17 @@ that display (@pxref{Deleting Frames}).
@node Frame Parameters
@section Frame Parameters
A frame has many parameters that control its appearance and behavior.
A frame has many parameters that control its appearance and behavior.
Just what parameters a frame has depends on what display mechanism it
uses.
Frame parameters exist for the sake of window systems. A terminal frame
has a few parameters, mostly for compatibility's sake; only the @code{height},
@code{width}, @code{name}, @code{title}, @code{buffer-list} and
@code{buffer-predicate} parameters do something special.
Frame parameters exist mostly for the sake of window systems. A
terminal frame has a few parameters, mostly for compatibility's sake;
only the @code{height}, @code{width}, @code{name}, @code{title},
@code{menu-bar-lines}, @code{buffer-list} and @code{buffer-predicate}
parameters do something special. If the terminal supports colors, the
parameters @code{foreground-color}, @code{background-color},
@code{background-mode} and @code{display-type} are also meaningful.
@menu
* Parameter Access:: How to change a frame's parameters.
@ -222,7 +237,7 @@ created initial frame.
If these settings affect the frame geometry and appearance, you'll see
the frame appear with the wrong ones and then change to the specified
ones. If that bothers you, you can specify the same geometry and
appearance with X resources; those do take affect before the frame is
appearance with X resources; those do take effect before the frame is
created. @xref{Resources X,, X Resources, emacs, The GNU Emacs Manual}.
X resource settings typically apply to all frames. If you want to
@ -391,7 +406,9 @@ ordered most-recently-selected first.
@item font
The name of the font for displaying text in the frame. This is a
string, either a valid font name for your system or the name of an Emacs
fontset (@pxref{Fontsets}).
fontset (@pxref{Fontsets}). Changing this frame parameter on a frame,
also changes the font-related attributes of the default face on that
frame.
@item auto-raise
Whether selecting the frame raises it (non-@code{nil} means yes).
@ -424,30 +441,40 @@ 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
window system defines the meaningful color names.
If you set the @code{foreground-color} frame parameter, you should
call @code{frame-update-face-colors} to update faces accordingly.
window system defines the meaningful color names. Changing this
parameter is equivalent to changing the foreground color of the face
@code{default} on the frame in question.
@item background-color
The color to use for the background of characters.
If you set the @code{background-color} frame parameter, you should
call @code{frame-update-face-colors} to update faces accordingly.
@xref{Face Functions}.
The color to use for the background of characters. Changing this
parameter is equivalent to changing the foreground color of the face
@code{default} on the frame in question.
@item background-mode
This parameter is either @code{dark} or @code{light}, according
to whether the background color is a light one or a dark one.
@item mouse-color
The color for the mouse pointer.
The color for the mouse pointer. Changing this parameter is equivalent
to changing the background color of face @code{mouse}.
@item cursor-color
The color for the cursor that shows point.
The color for the cursor that shows point. Changing this parameter is
equivalent to changing the background color of face @code{cursor}.
@item border-color
The color for the border of the frame.
The color for the border of the frame. Changing this parameter is
equivalent to changing the background color of face @code{border}.
@item scroll-bar-foreground
If non-@code{nil}, the color for the foreground of scroll bars.
Changing this parameter is equivalent to setting the foreground color of
face @code{scroll-bar}.
@item scroll-bar-background
If non-@code{nil}, the color for the background of scroll bars.
Changing this parameter is equivalent to setting the foreground color of
face @code{scroll-bar}.
@item display-type
This parameter describes the range of possible colors that can be used
@ -482,6 +509,17 @@ The default is 1. @xref{Menu Bar}. (In Emacs versions that use the X
toolkit, there is only one menu bar line; all that matters about the
number you specify is whether it is greater than zero.)
@item screen-gamma
If this is a number, Emacs performs ``gamma correction'' on colors. The
value should be the screen gamma of your display, a floating point
number. Usual PC monitors have a screen gamma of 2.2. Smaller values
result in darker colors; you might want to try a screen gamma of 1.5 for
LCD color displays. The viewing gamma Emacs uses is 0.4545 (1/2.2).
@item tool-bar-lines
The number of lines to use for the toolbar. A value of @code{nil} means
don't display a tool bar.
@ignore
@item parent-id
@c ??? Not yet working.
@ -755,7 +793,7 @@ upper left corner, down and to the right, until it reaches the window at
the lower right corner (always the minibuffer window, if the frame has
one), and then it moves back to the top. @xref{Cyclic Window Ordering}.
@defun frame-top-window frame
@defun frame-first-window frame
This returns the topmost, leftmost window of frame @var{frame}.
@end defun
@ -1309,180 +1347,160 @@ like the way successive kills in Emacs move down the kill ring.
@defvar selection-coding-system
@tindex selection-coding-system
This variable specifies the coding system to use when reading and
writing a selections, the clipboard, or a cut buffer. @xref{Coding
writing selections, the clipboard, or a cut buffer. @xref{Coding
Systems}. The default is @code{compound-text}.
@end defvar
@need 1500
@node Font Names
@section Looking up Font Names
@cindex clipboard support (for MS-Windows)
When Emacs runs on MS-Windows, it does not implement X selections in
general, but it it does support the clipboard. @code{x-get-selection}
and @code{x-set-selection} on MS-Windows support the text data type
only; if the clipboard holds other types of data, Emacs treats the
clipboard as empty.
@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 @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
@samp{?} character matches any single character. Pattern matching
of font names ignores case.
If you specify @var{face} and @var{frame}, @var{face} should be a face name
(a symbol) and @var{frame} should be a frame.
The optional argument @var{maximum} sets a limit on how many fonts to
return. If this is non-@code{nil}, then the return value is truncated
after the first @var{maximum} matching fonts. Specifying a small value
for @var{maximum} can make this function much faster, in cases where
many fonts match the pattern.
@end defun
@node Fontsets
@section Fontsets
A @dfn{fontset} is a list of fonts, each assigned to a range of
character codes. An individual font cannot display the whole range of
characters that Emacs supports, but a fontset can. Fontsets have names,
just as fonts do, and you can use a fontset name in place of a font name
when you specify the ``font'' for a frame or a face. Here is
information about defining a fontset under Lisp program control.
@defun create-fontset-from-fontset-spec fontset-spec &optional style-variant-p noerror
This function defines a new fontset according to the specification
string @var{fontset-spec}. The string should have this format:
@smallexample
@var{fontpattern}, @r{[}@var{charsetname}:@var{fontname}@r{]@dots{}}
@end smallexample
@noindent
Whitespace characters before and after the commas are ignored.
The first part of the string, @var{fontpattern}, should have the form of
a standard X font name, except that the last two fields should be
@samp{fontset-@var{alias}}.
The new fontset has two names, one long and one short. The long name is
@var{fontpattern} in its entirety. The short name is
@samp{fontset-@var{alias}}. You can refer to the fontset by either
name. If a fontset with the same name already exists, an error is
signaled, unless @var{noerror} is non-@code{nil}, in which case this
function does nothing.
If optional argument @var{style-variant-p} is non-@code{nil}, that says
to create bold, italic and bold-italic variants of the fontset as well.
These variant fontsets do not have a short name, only a long one, which
is made by altering @var{fontpattern} to indicate the bold or italic
status.
The specification string also says which fonts to use in the fontset.
See below for the details.
@end defun
The construct @samp{@var{charset}:@var{font}} specifies which font to
use (in this fontset) for one particular character set. Here,
@var{charset} is the name of a character set, and @var{font} is the font
to use for that character set. You can use this construct any number of
times in the specification string.
For the remaining character sets, those that you don't specify
explicitly, Emacs chooses a font based on @var{fontpattern}: it replaces
@samp{fontset-@var{alias}} with a value that names one character set.
For the @sc{ASCII} character set, @samp{fontset-@var{alias}} is replaced
with @samp{ISO8859-1}.
In addition, when several consecutive fields are wildcards, Emacs
collapses them into a single wildcard. This is to prevent use of
auto-scaled fonts. Fonts made by scaling larger fonts are not usable
for editing, and scaling a smaller font is not useful because it is
better to use the smaller font in its own size, which Emacs does.
Thus if @var{fontpattern} is this,
@example
-*-fixed-medium-r-normal-*-24-*-*-*-*-*-fontset-24
@end example
@noindent
the font specification for ASCII characters would be this:
@example
-*-fixed-medium-r-normal-*-24-*-ISO8859-1
@end example
@noindent
and the font specification for Chinese GB2312 characters would be this:
@example
-*-fixed-medium-r-normal-*-24-*-gb2312*-*
@end example
You may not have any Chinese font matching the above font
specification. Most X distributions include only Chinese fonts that
have @samp{song ti} or @samp{fangsong ti} in the @var{family} field. In
such a case, @samp{Fontset-@var{n}} can be specified as below:
@smallexample
Emacs.Fontset-0: -*-fixed-medium-r-normal-*-24-*-*-*-*-*-fontset-24,\
chinese-gb2312:-*-*-medium-r-normal-*-24-*-gb2312*-*
@end smallexample
@noindent
Then, the font specifications for all but Chinese GB2312 characters have
@samp{fixed} in the @var{family} field, and the font specification for
Chinese GB2312 characters has a wild card @samp{*} in the @var{family}
field.
@defopt x-select-enable-clipboard
If this is non-@code{nil}, the Emacs yank functions consult the
clipboard before the primary selection, and the kill functions store in
the clipboard as well as the primary selection. Otherwise they do not
access the clipboard at all. The default is @code{nil} on most systems,
but @code{t} on MS-Windows.
@end defopt
@node Color Names
@section Color Names
@defun x-color-defined-p color &optional frame
These functions provide a way to determine which color names are
valid, and what they look like.
@defun color-defined-p color &optional frame
@tindex color-defined-p
This function reports whether a color name is meaningful. It returns
@code{t} if so; otherwise, @code{nil}. The argument @var{frame} says
which frame's display to ask about; if @var{frame} is omitted or
@code{nil}, the selected frame is used.
Note that this does not tell you whether the display you are using
really supports that color. You can ask for any defined color on any
kind of display, and you will get some result---that is how the X server
works. Here's an approximate way to test whether your display supports
the color @var{color}:
really supports that color. When using X, you can ask for any defined
color on any kind of display, and you will get some result---typically,
the best it knows how to do. Here's an approximate way to test whether
your display supports the color @var{color}:
@example
(defun x-color-supported-p (color &optional frame)
(and (x-color-defined-p color frame)
(and (color-defined-p color frame)
(or (x-display-color-p frame)
(member color '("black" "white"))
(and (> (x-display-planes frame) 1)
(equal color "gray")))))
@end example
This function used to be called @code{x-color-defined-p},
and that name is still supported as an alias.
@end defun
@defun x-color-values color &optional frame
@defun defined-colors &optional frame
@tindex defined-colors
This function returns a list of the color names that are defined
and supported on frame @var{frame} (default, the selected frame).
This function used to be called @code{x-defined-colors},
and that name is still supported as an alias.
@end defun
@defun color-values color &optional frame
@tindex color-values
This function returns a value that describes what @var{color} should
ideally look like. If @var{color} is defined, the value is a list of
three integers, which give the amount of red, the amount of green, and
the amount of blue. Each integer ranges in principle from 0 to 65535,
but in practice no value seems to be above 65280. If @var{color} is not
defined, the value is @code{nil}.
but in practice no value seems to be above 65280. This kind
of three-element list is called an @dfn{rgb value}.
If @var{color} is not defined, the value is @code{nil}.
@example
(x-color-values "black")
(color-values "black")
@result{} (0 0 0)
(x-color-values "white")
(color-values "white")
@result{} (65280 65280 65280)
(x-color-values "red")
(color-values "red")
@result{} (65280 0 0)
(x-color-values "pink")
(color-values "pink")
@result{} (65280 49152 51968)
(x-color-values "hungry")
(color-values "hungry")
@result{} nil
@end example
The color values are returned for @var{frame}'s display. If @var{frame}
is omitted or @code{nil}, the information is returned for the selected
frame's display.
This function used to be called @code{x-color-values},
and that name is still supported as an alias.
@end defun
@node Text Terminal Colors
@section Text Terminal Colors
@cindex colors on text-only terminals
Emacs can display color on text-only terminals, starting with version
21. These terminals support only a small number of colors, and the
computer uses small integers to select colors on the terminal. This
means that the computer cannot reliably tell what the selected color
looks like; instead, you have to inform your application which small
integers correspond to which colors. However, Emacs does know the
standard set of colors and will try to use them automatically.
@cindex rgb value
Several of these functions use or return @dfn{rgb values}. An rgb
value is a list of three integers, which give the amount of red, the
amount of green, and the amount of blue. Each integer ranges in
principle from 0 to 65535, but in practice the largest value used is
65280.
@defun tty-define-color name number &optional rgb
@tindex tty-define-color
This function associates the color name @var{name} with
color number @var{number} on the terminal.
The optional argument @var{rgb}, if specified, is an rgb value; it says
what the color actually looks like. If you do not specify @var{rgb},
then this color cannot be used by @code{tty-color-approximate} to
approximate other colors, because Emacs does not know what it looks
like.
@end defun
@defun tty-clear-colors
@tindex tty-clear-colors
This function clears the table of defined colors for a text-only terminal.
@end defun
@defvar tty-color-alist
@tindex tty-color-alist
This variable holds an alist recording the colors supported by the
terminal.
Each element has the form @code{(@var{name} @var{number} . @var{rgb})}
or @code{(@var{name} @var{number})}. Here, @var{name} is the color
name, @var{number} is the number used to specify it to the terminal.
If present, @var{rgb} is an rgb value that says what the color
actually looks like.
@end defun
@defun tty-color-approximate rgb
@tindex tty-color-approximate
This function finds the closest available color, among those in
@code{tty-color-alist}, to that described by the rgb value @var{rgb}.
@end defun
@defun tty-color-translate color
@tindex tty-color-translate
This function finds the closest available color, among those in
@code{tty-color-alist}, to the name @var{color}. If that name
is not defined, the value is @code{nil}.
@var{color} can be an X-style @code{#@var{xxxyyyzzz}} specification
instead of an actual name.
@end defun
@node Resources

1
lispref/functions.texi
View file

@ -879,6 +879,7 @@ comment:
(function @var{symbol}) @equiv{} (quote @var{symbol}) @equiv{} '@var{symbol}
@end example
@cindex @samp{#'} syntax
The read syntax @code{#'} is a short-hand for using @code{function}.
For example,

40
lispref/internals.texi
View file

@ -97,7 +97,7 @@ installation directory for Lisp files when you install Emacs.
@item
Specify a non-@code{nil} value for
@code{byte-compile-dynamic-docstrings} as a local variable in each these
@code{byte-compile-dynamic-docstrings} as a local variable in each of these
files, and load them with either @file{site-load.el} or
@file{site-init.el}. (This method has the drawback that the
documentation strings take up space in Emacs all the time.)
@ -107,7 +107,7 @@ documentation strings take up space in Emacs all the time.)
@file{site-init.el} that would alter any of the features that users
expect in an ordinary unmodified Emacs. If you feel you must override
normal features for your site, do it with @file{default.el}, so that
users can override your changes if they wish. @xref{Start-up Summary}.
users can override your changes if they wish. @xref{Startup Summary}.
@defun dump-emacs to-file from-file
@cindex unexec
@ -125,7 +125,7 @@ you must run Emacs with @samp{-batch}.
Emacs Lisp uses two kinds of storage for user-created Lisp objects:
@dfn{normal storage} and @dfn{pure storage}. Normal storage is where
all the new data created during an Emacs session is kept; see the
all the new data created during an Emacs session are kept; see the
following section for information on normal storage. Pure storage is
used for certain data in the preloaded standard Lisp files---data that
should never change during actual use of Emacs.
@ -142,8 +142,8 @@ increase the compilation parameter @code{PURESIZE} in the file
preload additional libraries or add features to the standard ones.
@defun purecopy object
This function makes a copy of @var{object} in pure storage and returns
it. It copies strings by simply making a new string with the same
This function makes a copy in pure storage of @var{object}, and returns
it. It copies a string by simply making a new string with the same
characters in pure storage. It recursively copies the contents of
vectors and cons cells. It does not make copies of other objects such
as symbols, but just returns them unchanged. It signals an error if
@ -553,10 +553,10 @@ you use @code{GCPRO2}, you must declare @code{gcpro1} and @code{gcpro2}.
Alas, we can't explain all the tricky details here.
You must not use C initializers for static or global variables unless
they are never written once Emacs is dumped. These variables with
initializers are allocated in an area of memory that becomes read-only
(on certain operating systems) as a result of dumping Emacs. @xref{Pure
Storage}.
the variables are never stored in once Emacs is dumped. These variables
with initializers are allocated in an area of memory that becomes
read-only (on certain operating systems) as a result of dumping Emacs.
@xref{Pure Storage}.
Do not use static variables within functions---place all static
variables at top level in the file. This is necessary because Emacs on
@ -587,16 +587,19 @@ file, add to it a @code{syms_of_@var{filename}} (e.g.,
of these functions are called, and add a call to
@code{syms_of_@var{filename}} there.
@vindex byte-boolean-vars
The function @code{syms_of_@var{filename}} is also the place to define
any C variables that are to be visible as Lisp variables.
@code{DEFVAR_LISP} makes a C variable of type @code{Lisp_Object} visible
in Lisp. @code{DEFVAR_INT} makes a C variable of type @code{int}
visible in Lisp with a value that is always an integer.
@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}.
with a value that is either @code{t} or @code{nil}. Note that variables
defined with @code{DEFVAR_BOOL} are automatically added to the list
@code{byte-boolean-vars} used by the byte compiler.
If you define a file-scope C variable of type @code{Lisp_Object},
you must protect it for garbage-collection by calling @code{staticpro}
you must protect it from garbage-collection by calling @code{staticpro}
in @code{syms_of_@var{filename}}, like this:
@example
@ -681,6 +684,11 @@ number of arguments. They work by calling @code{Ffuncall}.
@file{lisp.h} contains the definitions for some important macros and
functions.
If you define a function which is side-effect free, update the code in
@file{byte-opt.el} which binds @code{side-effect-free-fns} and
@code{side-effect-and-error-free-fns} to include it. This will help the
optimizer.
@node Object Internals
@appendixsec Object Internals
@cindex object internals
@ -729,9 +737,9 @@ This field contains the time when the buffer was last saved, as an integer.
@item modtime
This field contains the modification time of the visited file. It is
set when the file is written or read. Every time the buffer is written
to the file, this field is compared to the modification time of the
file. @xref{Buffer Modification}.
set when the file is written or read. Before writing the buffer into a
file, this field is compared to the modification time of the file to see
if the file has changed on disk. @xref{Buffer Modification}.
@item auto_save_modified
This field contains the time when the buffer was last auto-saved.
@ -872,7 +880,9 @@ the screen is @w{line 0}.)
The height of the window, measured in lines.
@item width
The width of the window, measured in columns.
The width of the window, measured in columns. This width includes the
scroll bar and fringes, and/or the separator line on the right of the
window (if any).
@item next
This is the window that is the next in the chain of siblings. It is

31
lispref/intro.texi
View file

@ -343,7 +343,7 @@ the ``copyright'' line and a pointer to where the full notice is found.
@smallexample
@var{one line to give the program's name and an idea of what it does.}
Copyright (C) 19@var{yy} @var{name of author}
Copyright (C) @var{year} @var{name of author}
This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License
@ -366,7 +366,7 @@ If the program is interactive, make it output a short notice like this
when it starts in an interactive mode:
@smallexample
Gnomovision version 69, Copyright (C) 19@var{yy} @var{name of author}
Gnomovision version 69, Copyright (C) @var{year} @var{name of author}
Gnomovision comes with ABSOLUTELY NO WARRANTY; for details
type `show w'. This is free software, and you are welcome
to redistribute it under certain conditions; type `show c'
@ -521,7 +521,7 @@ worry about it; this manual is self-contained.
@pindex cl
A certain amount of Common Lisp emulation is available via the
@file{cl} library @xref{Top,, Common Lisp Extension, cl, Common Lisp
@file{cl} library. @xref{Top,, Common Lisp Extension, cl, Common Lisp
Extensions}.
Emacs Lisp is not at all influenced by Scheme; but the GNU project has
@ -556,10 +556,9 @@ addressed as ``you''. ``The user'' is the person who uses Lisp
programs, including those you write.
@cindex fonts
Examples of Lisp code appear in this font or form: @code{(list 1 2
3)}. Names that represent metasyntactic variables, or arguments to a
function being described, appear in this font or form:
@var{first-number}.
Examples of Lisp code are formatted like this: @code{(list 1 2 3)}.
Names that represent metasyntactic variables, or arguments to a function
being described, are formatted like this: @var{first-number}.
@node nil and t
@subsection @code{nil} and @code{t}
@ -685,13 +684,13 @@ the echo area.
@subsection Buffer Text Notation
@cindex buffer text notation
Some examples show modifications to text in a buffer, with ``before''
and ``after'' versions of the text. These examples show the contents of
the buffer in question between two lines of dashes containing the buffer
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
currently located.)
Some examples describe modifications to the contents of a buffer, by
showing the ``before'' and ``after'' versions of the text. These
examples show the contents of the buffer in question between two lines
of dashes containing the buffer 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 currently located.)
@example
---------- Buffer: foo ----------
@ -900,7 +899,9 @@ emacs-build-time
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.
time you build Emacs in any given directory. A value with three numeric
components, such as @code{"20.3.9.1"}, indicates an unreleased test
version.
@end defvar
The following two variables have existed since Emacs version 19.23:

252
lispref/keymaps.texi
View file

@ -124,17 +124,17 @@ completely masks any lower-precedence keymap.
@item @var{vector}
If an element of a keymap is a vector, the vector counts as bindings for
all the @sc{ASCII} characters, codes 0 through 127; vector element
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
@sc{ascii} character, even if the vector contains @code{nil} for that
character. Such a binding of @code{nil} overrides any default key
binding in the keymap, for @sc{ASCII} characters. However, default
bindings are still meaningful for events other than @sc{ASCII}
binding in the keymap, for @sc{ascii} characters. However, default
bindings are still meaningful for events other than @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.
@ -215,8 +215,8 @@ otherwise. More precisely, this function tests for a list whose
@c ??? This should come after make-sparse-keymap
@defun make-keymap &optional prompt
This function creates and returns a new full keymap (i.e., one
containing a vector of length 128 for defining all the @sc{ASCII}
characters). The new keymap initially binds all @sc{ASCII} characters
containing a vector of length 128 for defining all the @sc{ascii}
characters). The new keymap initially binds all @sc{ascii} characters
to @code{nil}, and does not bind any other kind of event.
@example
@ -567,7 +567,7 @@ other.
This function returns the current buffer's local keymap, or @code{nil}
if it has none. In the following example, the keymap for the
@samp{*scratch*} buffer (using Lisp Interaction mode) is a sparse keymap
in which the entry for @key{ESC}, @sc{ASCII} code 27, is another sparse
in which the entry for @key{ESC}, @sc{ascii} code 27, is another sparse
keymap.
@example
@ -953,7 +953,7 @@ This variable is the meta-prefix character code. It is used when
translating a meta character to a two-character sequence so it can be
looked up in a keymap. For useful results, the value should be a prefix
event (@pxref{Prefix Keys}). The default value is 27, which is the
@sc{ASCII} code for @key{ESC}.
@sc{ascii} code for @key{ESC}.
As long as the value of @code{meta-prefix-char} remains 27, key
lookup translates @kbd{M-b} into @kbd{@key{ESC} b}, which is normally
@ -1256,6 +1256,35 @@ redefines @kbd{C-x C-\} to move down a line.
redefines the first (leftmost) mouse button, typed with the Meta key, to
set point where you click.
@cindex non-ASCII text in keybindings
Be careful when using non-@sc{ascii} text characters in Lisp
specifications of keys to bind. If these are read as multibyte text, as
they usually will be in a Lisp file (@pxref{Loading Non-ASCII}), you
must type the keys as multibyte too. For instance, if you use this:
@smallexample
(global-set-key "@"o" 'my-function) ; bind o-umlaut
@end smallexample
@noindent
or
@smallexample
(global-set-key ?@"o 'my-function) ; bind o-umlaut
@end smallexample
@noindent
and your language environment is multibyte Latin-1, these commands
actually bind the multibyte character with code 2294, not the unibyte
Latin-1 character with code 246 (@kbd{M-v}). In order to use this
binding, you need to enter the multibyte Latin-1 character as keyboard
input. One way to do this is by using an appropriate input method
(@pxref{Input Methods, , Input Methods, emacs,The GNU Emacs Manual}).
If you want to use a unibyte character in the key binding, you can
construct the key sequence string using @code{multibyte-char-to-unibyte}
or @code{string-make-unibyte} (@pxref{Converting Representations}).
@deffn Command global-set-key key definition
This function sets the binding of @var{key} in the current global map
to @var{definition}.
@ -1431,7 +1460,7 @@ If @var{firstonly} is @code{non-ascii}, then the value is a single
string representing the first key sequence found, rather than a list of
all possible key sequences. If @var{firstonly} is @code{t}, then the
value is the first key sequence, except that key sequences consisting
entirely of @sc{ASCII} characters (or meta variants of @sc{ASCII}
entirely of @sc{ascii} characters (or meta variants of @sc{ascii}
characters) are preferred to all other key sequences.
If @var{noindirect} is non-@code{nil}, @code{where-is-internal} doesn't
@ -1457,13 +1486,13 @@ listing includes only keys that start with @var{prefix}.
The listing describes meta characters as @key{ESC} followed by the
corresponding non-meta character.
When several characters with consecutive @sc{ASCII} codes have the
When several characters with consecutive @sc{ascii} codes have the
same definition, they are shown together, as
@samp{@var{firstchar}..@var{lastchar}}. In this instance, you need to
know the @sc{ASCII} codes to understand which characters this means.
know the @sc{ascii} codes to understand which characters this means.
For example, in the default global map, the characters @samp{@key{SPC}
..@: ~} are described by a single line. @key{SPC} is @sc{ASCII} 32,
@kbd{~} is @sc{ASCII} 126, and the characters between them include all
..@: ~} are described by a single line. @key{SPC} is @sc{ascii} 32,
@kbd{~} is @sc{ascii} 126, and the characters between them include all
the normal printing characters, (e.g., letters, digits, punctuation,
etc.@:); all these characters are bound to @code{self-insert-command}.
@end deffn
@ -1483,6 +1512,7 @@ work with the keyboard also.
* Keyboard Menus:: How they actuate it with the keyboard.
* Menu Example:: Making a simple menu.
* Menu Bar:: How to customize the menu bar.
* Tool Bar:: A tool bar is a row of images.
* Modifying Menus:: How to add new items to a menu.
@end menu
@ -1509,10 +1539,11 @@ an existing menu, you can specify its position in the menu using
@menu
* Simple Menu Items:: A simple kind of menu key binding,
limited in capabilities.
* Alias Menu Items:: Using command aliases in menu items.
* Extended Menu Items:: More powerful menu item definitions
let you specify keywords to enable
various features.
* Menu Separators:: Drawing a horizontal line through a menu.
* Alias Menu Items:: Using command aliases in menu items.
@end menu
@node Simple Menu Items
@ -1591,7 +1622,8 @@ the item looks like this:
@end example
@noindent
where a string consisting of two or more dashes specifies a separator line.
A string starting with two or more dashes specifies a separator line;
see @ref{Menu Separators}.
To define a real menu item which can be selected, the extended format
item looks like this:
@ -1609,11 +1641,12 @@ string. Thus, the string need not be a constant. The third element,
other information. Here is a table of the properties that are supported:
@table @code
@item :enable FORM
@item :enable @var{form}
The result of evaluating @var{form} determines whether the item is
enabled (non-@code{nil} means yes).
enabled (non-@code{nil} means yes). If the item is not enabled,
you can't really click on it.
@item :visible FORM
@item :visible @var{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
@ -1684,6 +1717,80 @@ when it is called, its argument will be @var{real-binding}. The
function should return the binding to use instead.
@end table
@node Menu Separators
@subsubsection Menu Separators
@cindex menu separators
A menu separator is a kind of menu item that doesn't display any
text--instead, it divides the menu into subparts with a horizontal line.
A separator looks like this in the menu keymap:
@example
(menu-item @var{separator-type})
@end example
@noindent
where @var{separator-type} is a string starting with two or more dashes.
In the simplest case, @var{separator-type} consists of only dashes.
That specifies the default kind of separator. (For compatibility,
@code{""} and @code{-} also count as separators.)
Starting in Emacs 21, certain other values of @var{separator-type}
specify a different style of separator. Here is a table of them:
@table @code
@item "--no-line"
@itemx "--space"
An extra vertical space, with no actual line.
@item "--single-line"
A single line in the menu's foreground color.
@item "--double-line"
A double line in the menu's foreground color.
@item "--single-dashed-line"
A single dashed line in the menu's foreground color.
@item "--double-dashed-line"
A double dashed line in the menu's foreground color.
@item "--shadow-etched-in"
A single line with a 3D sunken appearance. This is the default,
used separators consisting of dashes only.
@item "--shadow-etched-out"
A single line with a 3D raised appearance.
@item "--shadow-etched-in-dash"
A single dashed line with a 3D sunken appearance.
@item "--shadow-etched-out-dash"
A single dashed line with a 3D raised appearance.
@item "--shadow-double-etched-in"
Two lines with a 3D sunken appearance.
@item "--shadow-double-etched-out"
Two lines with a 3D raised appearance.
@item "--shadow-double-etched-in-dash"
Two dashed lines with a 3D sunken appearance.
@item "--shadow-double-etched-out-dash"
Two dashed lines with a 3D raised appearance.
@end table
You can also give these names in another style, adding a colon after
the double-dash and replacing each single dash with capitalization of
the following word. Thus, @code{"--:singleLine"}, is equivalent to
@code{"--single-line"}.
Some systems and display toolkits don't really handle all of these
separator types. If you use a type that isn't supported, the menu
displays a similar kind of separator that is supported.
@node Alias Menu Items
@subsubsection Alias Menu Items
@ -1978,6 +2085,115 @@ displaying a submenu. You can use it to update submenus whose contents
should vary.
@end defvar
@node Tool Bar
@subsection Tool bars
@cindex tool bar
A @dfn{tool bar} is a row of icons at the top of a frame, that execute
commands when you click on them---in effect, a kind of graphical menu
bar. Emacs supports tool bars starting with version 21.
The frame parameter @code{tool-bar-lines} (X resource @samp{toolBar})
controls how may lines' worth of height to reserve for the tool bar. A
zero value suppresses the tool bar. If the value is nonzero, and
@code{auto-resize-tool-bars} is non-@code{nil}, the tool bar expands and
contracts automatically as needed to hold the specified contents.
The tool bar contents are controlled by a menu keymap attached to a
fake ``function key'' called @code{tool-bar} (much like the way the menu
bar is controlled). So you define a tool bar item using
@code{define-key}, like this:
@example
(define-key global-map [tool-bar @var{key}] @var{item})
@end example
@noindent
where @var{key} is a fake ``function key'' to distinguish this item from
other items, and @var{item} is a menu item key binding (@pxref{Extended
Menu Items}), which says how to display this item and how it behaves.
The usual menu keymap item properties, @code{:visible},
@code{:enable}, @code{:button}, and @code{:filter}, are useful in
tool bar bindings and have their normal meanings. The @var{real-binding}
in the item must be a command, not a keymap; in other words, it does not
work to define a tool bar icon as a prefix key.
The @code{:help} property is meaningful, and specifies a ``help-echo''
string to display while the mouse is on that item.
In addition, you should use the @code{:image} property;
this is how you specify the image to display in the tool bar:
@table @code
@item :image @var{image}
@var{images} is either a single image specification or a vector of four
image specifications. If you use a vector of four,
one of them is used, depending on circumstances:
@table @asis
@item item 0
Used when the iitem is enabled and selected.
@item item 1
Used when the item is enabled and deselected.
@item item 2
Used when the item is disabled and selected.
@item item 3
Used when the item is disabled and deselected.
@end table
@end table
@tindex auto-resize-tool-bar
@defvar auto-resize-tool-bar
If this variable is non-@code{nil}, the tool bar automatically resizes to
show all defined tool bar items---but not larger than a quarter of the
frame's height.
@end defvar
@tindex auto-raise-tool-bar-items
@defvar auto-raise-tool-bar-items
If this variable is non-@code{nil}, tool bar items display
in raised form when the mouse moves over them.
@end defvar
@tindex tool-bar-item-margin
@defvar tool-bar-item-margin
This variable specifies an extra margin to add around tool bar items.
The value is an integer, a number of pixels. The default is 1.
@end defvar
@tindex tool-bar-item-relief
@defvar tool-bar-item-relief
This variable specifies the shadow width for tool bar items.
The value is an integer, a number of pixels. The default is 3.
@end defvar
You can define a special meaning for clicking on a tool bar item with
the shift, control, meta, etc., modifiers. You do this by setting up
additional items that relate to the original item through the fake
function keys. Specifically, the additional items should use the
modified versions of the same fake function key used to name the
original item.
Thus, if the original item was defined this way,
@example
(define-key global-map [tool-bar shell]
'(menu-item "Shell" shell
:image (image :type xpm :file "shell.xpm")))
@end example
@noindent
then here is how you can define clicking on the same tool bar image with
the shift modifier:
@example
(define-key global-map [tool-bar S-shell] 'some-command)
@end example
@xref{Function Keys}, for more information about how to add modifiers to
function keys.
@node Modifying Menus
@subsection Modifying Menus

37
lispref/lists.texi
View file

@ -302,6 +302,26 @@ This is in contrast to @code{cdr}, which signals an error if
@end example
@end defun
@tindex pop
@defmac pop listname
This macro is a way of examining the @sc{car} of a list,
and taking it off the list, all at once. It is new in Emacs 21.
It operates on the list which is stored in the symbol @var{listname}.
It removes this element from the list by setting @var{listname}
to the @sc{cdr} of its old value---but it also returns the @sc{car}
of that list, which is the element being removed.
@example
x
@result{} (a b c)
(pop x)
@result{} a
x
@result{} (b c)
@end example
@end defmac
@defun nth n list
This function returns the @var{n}th element of @var{list}. Elements
are numbered starting with zero, so the @sc{car} of @var{list} is
@ -441,6 +461,13 @@ used in this example and the function named @code{list} described below;
any symbol can serve both purposes.
@end defun
@tindex push
@defmac push newelt listname
This macro provides an alternative way to write
@code{(setq @var{listname} (cons @var{newelt} @var{listname}))}.
It is new in Emacs 21.
@end defmac
@defun list &rest objects
This function creates a list with @var{objects} as its elements. The
resulting list is always @code{nil}-terminated. If no @var{objects}
@ -1509,4 +1536,14 @@ the associations of one copy without affecting the other:
@end smallexample
@end defun
@defun assoc-delete-all key alist
@tindex assoc-delete-all
This function deletes from @var{alist} all the elements whose @sc{car}
is @var{key}. It returns the modified alist.
@example
(assoc-delete-all 'foo
'((foo 1) (bar 2) (foo 3) (lose 4)))
@result{} ((bar 2) (lose 4))
@end example
@end defun

66
lispref/loading.texi
View file

@ -36,7 +36,7 @@ containing Lisp code.
@menu
* How Programs Do Loading:: The @code{load} function and others.
* Library Search:: Finding a library to load.
* Loading Non-ASCII:: Non-@sc{ASCII} characters in Emacs Lisp files.
* Loading Non-ASCII:: Non-@sc{ascii} characters in Emacs Lisp files.
* Autoload:: Setting up a function to autoload.
* Repeated Loading:: Precautions about loading a file twice.
* Named Features:: Loading a library if it isn't already loaded.
@ -257,10 +257,10 @@ subdirectories multiple levels down are added to @code{load-path}.
Not all subdirectories are included, though. Subdirectories whose
names do not start with a letter or digit are excluded. Subdirectories
named @file{RCS} are excluded. Also, a subdirectory which contains a
file named @file{.nosearch} is excluded. You can use these methods to
prevent certain subdirectories of the @file{site-lisp} directories from
being searched.
named @file{RCS} or @file{CVS} are excluded. Also, a subdirectory which
contains a file named @file{.nosearch} is excluded. You can use these
methods to prevent certain subdirectories of the @file{site-lisp}
directories from being searched.
If you run Emacs from the directory where it was built---that is, an
executable that has not been formally installed---then @code{load-path}
@ -287,7 +287,7 @@ tells @code{locate-library} to display the file name in the echo area.
@node Loading Non-ASCII
@section Loading Non-ASCII Characters
When Emacs Lisp programs contain string constants with non-@sc{ASCII}
When Emacs Lisp programs contain string constants with non-@sc{ascii}
characters, these can be represented within Emacs either as unibyte
strings or as multibyte strings (@pxref{Text Representations}). Which
representation is used depends on how the file is read into Emacs. If
@ -301,7 +301,7 @@ unibyte text, and its string constants will be unibyte strings.
To make the results more predictable, Emacs always performs decoding
into the multibyte representation when loading Lisp files, even if it
was started with the @samp{--unibyte} option. This means that string
constants with non-@sc{ASCII} characters translate into multibyte
constants with non-@sc{ascii} characters translate into multibyte
strings. The only exception is when a particular file specifies no
decoding.
@ -313,13 +313,13 @@ notice whether the user prefers unibyte or multibyte text, by checking
@code{default-enable-multibyte-characters}, and convert representations
appropriately.
In most Emacs Lisp programs, the fact that non-@sc{ASCII} strings are
In most Emacs Lisp programs, the fact that non-@sc{ascii} strings are
multibyte strings should not be noticeable, since inserting them in
unibyte buffers converts them to unibyte automatically. However, if
this does make a difference, you can force a particular Lisp file to be
interpreted as unibyte by writing @samp{-*-unibyte: t;-*-} in a
comment on the file's first line. With that designator, the file will
be unconditionally be interpreted as unibyte, even in an ordinary
unconditionally be interpreted as unibyte, even in an ordinary
multibyte Emacs session.
@node Autoload
@ -432,13 +432,20 @@ autoloads for all files in the current directory.
The same magic comment can copy any kind of form into
@file{loaddefs.el}. If the form following the magic comment is not a
function definition, it is copied verbatim. You can also use a magic
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 @kbd{M-x update-file-autoloads}
copies it to @file{loaddefs.el}, where it is executed while building
Emacs.
function-defining form or a @code{defcustom} form, it is copied
verbatim. ``Function-defining forms'' include @code{define-skeleton},
@code{define-derived-mode}, @code{define-generic-mode} and
@code{easy-mmode-define-minor-mode} as well as @code{defun} and
@code{defmacro}. To save space, a @code{defcustom} form is converted to
a @code{defvar} in @file{loaddefs.el}, with some additional information
if it uses @code{:require}.
You can also use a magic 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
@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:
@ -456,17 +463,17 @@ autoloading with a magic comment:
Here's what that produces in @file{loaddefs.el}:
@smallexample
(autoload 'doctor "doctor"
"\
(autoload 'doctor "doctor" "\
Switch to *doctor* buffer and start giving psychotherapy."
t)
@end smallexample
@noindent
The backslash and newline immediately following the double-quote are a
convention used only in the preloaded Lisp files such as
convention used only in the preloaded uncompiled Lisp files such as
@file{loaddefs.el}; they tell @code{make-docfile} to put the
documentation string in the @file{etc/DOC} file. @xref{Building Emacs}.
See also the commentary in @file{lib-src/make-docfile.c}.
@node Repeated Loading
@section Repeated Loading
@ -591,7 +598,9 @@ done.
When @code{require} is used at top level in a file, it takes effect
when you byte-compile that file (@pxref{Byte Compilation}) as well as
when you load it. This is in case the required package contains macros
that the byte compiler must know about.
that the byte compiler must know about. It also avoids byte-compiler
warnings for functions and variables defined in the file loaded with
@code{require}.
Although top-level calls to @code{require} are evaluated during
byte compilation, @code{provide} calls are not. Therefore, you can
@ -701,6 +710,8 @@ is defined, it is run as a normal hook before restoring the previous
definitions, @emph{instead of} the usual hook-removing actions. The
unload hook ought to undo all the global state changes made by the
library that might cease to work once the library is unloaded.
@code{unload-feature} can cause problems with libraries that fail to do
this, so it should be used with caution.
Ordinarily, @code{unload-feature} refuses to unload a library on which
other loaded libraries depend. (A library @var{a} depends on library
@ -741,7 +752,16 @@ The value of @code{load-history} may have one element whose @sc{car} is
by adding the symbols defined to the element for the file being visited,
rather than replacing that element. @xref{Eval}.
Preloaded libraries don't contribute to @code{load-history}.
Preloaded libraries don't contribute initially to @code{load-history}.
Instead, preloading writes information about preloaded libraries into a
file, which can be loaded later on to to add information to
@code{load-history} describing the preloaded files. This file is
installed in @code{exec-directory} and has a name of the form
@file{fns-@var{emacsversion}.el}.
@findex symbol-file
See the source for the function @code{symbol-file}, for an example of
code that loads this file to find functions in preloaded libraries.
@tindex loadhist-special-hooks
@defvar loadhist-special-hooks
@ -784,8 +804,8 @@ 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
loaded. Each element looks like this:
This variable holds an alist of expressions to evaluate if and when
particular libraries are loaded. Each element looks like this:
@example
(@var{filename} @var{forms}@dots{})

23
lispref/maps.texi
View file

@ -67,34 +67,35 @@ A sparse keymap used by Emacs Lisp mode.
@item facemenu-menu
@vindex facemenu-menu
The keymap that displays the Text Properties menu.
The sparse keymap that displays the Text Properties menu.
@item facemenu-background-menu
@vindex facemenu-background-menu
The keymap that displays the Background Color submenu of the Text
The sparse keymap that displays the Background Color submenu of the Text
Properties menu.
@item facemenu-face-menu
@vindex facemenu-face-menu
The keymap that displays the Face submenu of the Text Properties menu.
The sparse keymap that displays the Face submenu of the Text Properties menu.
@item facemenu-foreground-menu
@vindex facemenu-foreground-menu
The keymap that displays the Foreground Color submenu of the Text
The sparse keymap that displays the Foreground Color submenu of the Text
Properties menu.
@item facemenu-indentation-menu
@vindex facemenu-indentation-menu
The keymap that displays the Indentation submenu of the Text Properties menu.
The sparse keymap that displays the Indentation submenu of the Text
Properties menu.
@item facemenu-justification-menu
@vindex facemenu-justification-menu
The keymap that displays the Justification submenu of the Text
The sparse keymap that displays the Justification submenu of the Text
Properties menu.
@item facemenu-special-menu
@vindex facemenu-special-menu
The keymap that displays the Special Props submenu of the Text
The sparse keymap that displays the Special Props submenu of the Text
Properties menu.
@item function-key-map
@ -104,7 +105,7 @@ If there are none, then it contains an empty sparse keymap.
@item fundamental-mode-map
@vindex fundamental-mode-map
The local keymap for Fundamental mode.@*
The sparse keymap for Fundamental mode.@*
It is empty and should not be changed.
@item Helper-help-map
@ -132,7 +133,7 @@ bindings, unlike @code{function-key-map}. @xref{Translating Input}.
@item lisp-interaction-mode-map
@vindex lisp-interaction-mode-map
A sparse keymap used by Lisp mode.
A sparse keymap used by Lisp Interaction mode.
@item lisp-mode-map
@vindex lisp-mode-map
@ -171,10 +172,10 @@ where it describes the main use of the @kbd{C-c} prefix key.
@item occur-mode-map
@vindex occur-mode-map
A local keymap used by Occur mode.
A sparse keymap used by Occur mode.
@item query-replace-map
A local keymap used for responses in @code{query-replace} and related
A sparse 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
time.

2
lispref/markers.texi
View file

@ -136,7 +136,7 @@ integer or floating point) or a marker, @code{nil} otherwise.
@end defun
@node Creating Markers
@section Functions That Create Markers
@section Functions that Create Markers
When you create a new marker, you can make it point nowhere, or point
to the present position of point, or to the beginning or end of the

41
lispref/minibuf.texi
View file

@ -42,12 +42,26 @@ windows always appear at the bottom of a frame. (Sometimes frames have
no minibuffer window, and sometimes a special kind of frame contains
nothing but a minibuffer window; see @ref{Minibuffers and Frames}.)
The minibuffer's window is normally a single line. You can resize it
temporarily with the window sizing commands; it reverts to its normal
size when the minibuffer is exited. You can resize it permanently by
using the window sizing commands in the frame's other window, when the
minibuffer is not active. If the frame contains just a minibuffer, you
can change the minibuffer's size by changing the frame's size.
The text in the minibuffer always starts with the @dfn{prompt string},
the text that was specified by the program that is using the minibuffer
to tell the user what sort of input to type. This text is marked
read-only so you won't accidentally delete or change it. In other
respects, it is an ordinary part of the buffer contents, but certain
functions such as @code{erase-buffer}, @code{buffer-string},
@code{beginning-of-line}, @code{forward-word}, @code{forward-sentence},
and @code{forward-paragraph}, treat it a little bit specially. (In
older Emacs versions, the prompt was displayed using a special mechanism
and was not part of the buffer contents.)
@c ???
The minibuffer's window is normally a single line; it grows
automatically if necessary if the contents require more space. You can
explicitly resize it temporarily with the window sizing commands; it
reverts to its normal size when the minibuffer is exited. You can
resize it permanently by using the window sizing commands in the frame's
other window, when the minibuffer is not active. If the frame contains
just a minibuffer, you can change the minibuffer's size by changing the
frame's size.
If a command uses a minibuffer while there is an active minibuffer,
this is called a @dfn{recursive minibuffer}. The first minibuffer is
@ -724,7 +738,7 @@ see @ref{Completion Commands}.
@end defun
@node Completion Commands
@subsection Minibuffer Commands That Do Completion
@subsection Minibuffer Commands that Do Completion
This section describes the keymaps, commands and user options used in
the minibuffer to do completion.
@ -1483,9 +1497,16 @@ This function returns the prompt string of the currently active
minibuffer. If no minibuffer is active, it returns @code{nil}.
@end defun
@defun minibuffer-prompt-width
This function returns the display width of the prompt string of the
currently active minibuffer. If no minibuffer is active, it returns 0.
@tindex minubuffer-prompt-end
@defun minubuffer-prompt-end
This function, available starting in Emacs 21, returns the current
position of the end of the minibuffer prompt, if a minibuffer is
current. Otherwise, it returns zero.
@end defun
@defun minubuffer-prompt-width
This function returns the current display-width of the minibuffer
prompt, if a minibuffer is current. Otherwise, it returns zero.
@end defun
@defvar minibuffer-setup-hook

213
lispref/modes.texi
View file

@ -61,7 +61,7 @@ definition is distinct from that of Text mode, but was derived from it.
Rmail Edit mode offers an example of changing the major mode
temporarily for a buffer, so it can be edited in a different way (with
ordinary Emacs commands rather than Rmail commands). In such cases, the
temporary major mode usually has a command to switch back to the
temporary major mode usually provides 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
@ -70,8 +70,8 @@ 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
several major modes, in files such as @file{text-mode.el},
The standard GNU Emacs Lisp library directory tree contains the code
for several major modes, in files such as @file{text-mode.el},
@file{texinfo.el}, @file{lisp-mode.el}, @file{c-mode.el}, and
@file{rmail.el}. You can study these libraries to see how modes are
written. Text mode is perhaps the simplest major mode aside from
@ -245,7 +245,7 @@ with value @code{special}, put on as follows:
@end example
@noindent
This tells Emacs that new buffers created while the current buffer has
This tells Emacs that new buffers created while the current buffer is in
Funny mode should not inherit Funny mode. Modes such as Dired, Rmail,
and Buffer List use this feature.
@ -368,7 +368,7 @@ correspondingly more complicated. Here are excerpts from
@group
;; @r{Set syntax of chars up to 0 to class of chars that are}
;; @r{part of symbol names but not words.}
;; @r{(The number 0 is @code{48} in the @sc{ASCII} character set.)}
;; @r{(The number 0 is @code{48} in the @sc{ascii} character set.)}
(while (< i ?0)
(modify-syntax-entry i "_ " emacs-lisp-mode-syntax-table)
(setq i (1+ i)))
@ -782,7 +782,8 @@ individually or in combination. Minor modes would be better named
``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
A minor mode is not usually meant as a variation of a single major mode.
Usually they are general and can apply to many major modes. For
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.
@ -825,7 +826,7 @@ 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
If 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 set the variable.
@ -890,6 +891,40 @@ check for an existing element, to avoid duplication. For example:
You can also use @code{add-to-list} to add an element to this list
just once (@pxref{Setting Variables}).
Global minor modes distributed with Emacs should if possible support
enabling and disabling via Custom (@pxref{Customization}). To do this,
the first step is to define the mode variable with @code{defcustom}, and
specify @code{:type boolean}.
If just setting the variable is not sufficient to enable the mode, you
should also specify a @code{:set} method which enables the mode by
invoke the mode command. Note in the variable's documentation string that
setting the variable other than via Custom may not take effect.
Also mark the definition with an autoload cookie (@pxref{Autoload}),
and specify a @code{:require} so that customizing the variable will load
the library that defines the mode. This will copy suitable definitions
into @file{loaddefs.el} so that users can use @code{customize-option} to
enable the mode. For example:
@smallexample
@group
;;;###autoload
(defcustom msb-mode nil
"Toggle msb-mode.
Setting this variable directly does not take effect;
use either \\[customize] or the function `msb-mode'."
:set (lambda (symbol value)
(msb-mode (or value 0)))
:initialize 'custom-initialize-default
:version "20.4"
:type 'boolean
:group 'msb
:require 'msb)
@end group
@end smallexample
@node Keymaps and Minor Modes
@subsection Keymaps and Minor Modes
@ -908,15 +943,15 @@ standard one. The editor command loop handles this function specially.)
The key sequences bound in a minor mode should consist of @kbd{C-c}
followed by a punctuation character @emph{other than} @kbd{@{},
@kbd{@}}, @kbd{<}, @kbd{>}, @kbd{:} or @kbd{;}. (Those few punctuation
@kbd{@}}, @kbd{<}, @kbd{>}, @kbd{:}, and @kbd{;}. (Those few punctuation
characters are reserved for major modes.)
@node Easy-Mmode
@subsection Easy-Mmode
The easy-mmode package provides a convenient way of implementing a
minor mode; with it, you can specify everything about a simple minor
mode in one self-contained definition.
mode in one self-contained definition. It currently supports only
buffer-local minor modes, not global ones.
@defmac easy-mmode-define-minor-mode mode doc &optional init-value mode-indicator keymap
@tindex easy-mmode-define-minor-mode
@ -978,35 +1013,39 @@ mode is enabled. It initializes the keymap with key bindings for
@section Mode Line Format
@cindex mode line
Each Emacs window (aside from minibuffer windows) includes a mode line,
which displays status information about the buffer displayed in the
window. The mode line contains information about the buffer, such as its
name, associated file, depth of recursive editing, and the major and
minor modes.
Each Emacs window (aside from minibuffer windows) typically has a mode
line at the bottom, which displays status information about the buffer
displayed in the window. The mode line contains information about the
buffer, such as its name, associated file, depth of recursive editing,
and major and minor modes. A window can also have a @dfn{header
line}, which is much like the mode line but appears at the top of the
window (starting in Emacs 21).
This section describes how the contents of the mode line are
controlled. We include it in this chapter because much of the
This section describes how to control the contents of the mode line
and header line. We include it in this chapter because much of the
information displayed in the mode line relates to the enabled major and
minor modes.
@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 and column numbers).
windows for the same buffer use the same @code{mode-line-format}, so
their mode lines appear the same---except for scrolling percentages, and
line and column numbers, since those depend on point and on how the
window is scrolled. @code{header-line-format} is used likewise for
header lines.
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
changes from @code{nil} to @code{t} or vice-versa. If you modify any of
the variables referenced by @code{mode-line-format} (@pxref{Mode Line
Variables}), or any other variables and data structures that affect how
text is displayed (@pxref{Display}), you may want to force an update of
the mode line so as to display the new information or display it in
the new way.
The mode line and header line of a window are normally updated
whenever a different buffer is shown in the window, or when the buffer's
modified-status changes from @code{nil} to @code{t} or vice-versa. If
you modify any of the variables referenced by @code{mode-line-format}
(@pxref{Mode Line Variables}), or any other variables and data
structures that affect how text is displayed (@pxref{Display}), you may
want to force an update of the mode line so as to display the new
information or display it in the new way.
@c Emacs 19 feature
@defun force-mode-line-update
Force redisplay of the current buffer's mode line.
Force redisplay of the current buffer's mode line and header line.
@end defun
The mode line is usually displayed in inverse video; see
@ -1016,6 +1055,8 @@ Force redisplay of the current buffer's mode line.
* Mode Line Data:: The data structure that controls the mode line.
* Mode Line Variables:: Variables used in that data structure.
* %-Constructs:: Putting information into a mode line.
* Properties in Mode:: Using text properties in the mode line.
* Header Lines:: Like a mode line, but at the top.
@end menu
@node Mode Line Data
@ -1034,6 +1075,9 @@ The value of this variable is a mode line construct with overall
responsibility for the mode line format. The value of this variable
controls which other variables are used to form the mode line text, and
where they appear.
If you set this variable to @code{nil} in a buffer, that buffer does not
have a mode line. (This feature was added in Emacs 21.)
@end defvar
A mode line construct may be as simple as a fixed string of text, but
@ -1050,6 +1094,11 @@ variables that @code{mode-line-format} refers to.
A mode line construct may be a list, a symbol, or a string. If the
value is a list, each element may be a list, a symbol, or a string.
The mode line can display various faces, if the strings that control
it have the @code{face} property. @xref{Properties in Mode}. In
addition, the face @code{mode-line} is used as a default for the whole
mode line (@pxref{Standard Faces}).
@table @code
@cindex percent symbol in mode line
@item @var{string}
@ -1061,7 +1110,7 @@ is left justified). @xref{%-Constructs}.
@item @var{symbol}
A symbol as a mode line construct stands for its value. The value of
@var{symbol} is used as a mode line construct, in place of @var{symbol}.
However, the symbols @code{t} and @code{nil} are ignored; so is any
However, the symbols @code{t} and @code{nil} are ignored, as is any
symbol whose value is void.
There is one exception: if the value of @var{symbol} is a string, it is
@ -1072,14 +1121,19 @@ A list whose first element is a string or list means to process all the
elements recursively and concatenate the results. This is the most
common form of mode line construct.
@item (:eval @var{form})
A list whose first element is the symbol @code{:eval} says to evaluate
@var{form}, and use the result as a string to display.
(This feature is new as of Emacs 21.)
@item (@var{symbol} @var{then} @var{else})
A list whose first element is a symbol is a conditional. Its meaning
depends on the value of @var{symbol}. If the value is non-@code{nil},
the second element, @var{then}, is processed recursively as a mode line
element. But if the value of @var{symbol} is @code{nil}, the third
element, @var{else}, is processed recursively. You may omit @var{else};
then the mode line element displays nothing if the value of @var{symbol}
is @code{nil}.
A list whose first element is a symbol that is not a keyword specifies a
conditional. Its meaning depends on the value of @var{symbol}. If the
value is non-@code{nil}, the second element, @var{then}, is processed
recursively as a mode line element. But if the value of @var{symbol} is
@code{nil}, the third element, @var{else}, is processed recursively.
You may omit @var{else}; then the mode line element displays nothing if
the value of @var{symbol} is @code{nil}.
@item (@var{width} @var{rest}@dots{})
A list whose first element is an integer specifies truncation or
@ -1124,7 +1178,7 @@ directory.
" "
'global-mode-string
" %[("
'mode-name
'(:eval (mode-line-mode-name))
'mode-line-process
'minor-mode-alist
"%n"
@ -1268,7 +1322,7 @@ The default value of @code{default-mode-line-format} is this list:
global-mode-string
@group
" %[("
mode-name
(:eval (mode-line-mode-name))
mode-line-process
minor-mode-alist
"%n"
@ -1315,7 +1369,8 @@ The title (only on a window system) or the name of the selected frame.
The current column number of point.
@item %l
The current line number of point.
The current line number of point, counting within the accessible portion
of the buffer.
@item %*
@samp{%} if the buffer is read only (see @code{buffer-read-only}); @*
@ -1383,6 +1438,64 @@ The value of @code{global-mode-string}. Currently, only
@code{display-time} modifies the value of @code{global-mode-string}.
@end table
@node Properties in Mode
@subsection Properties in the Mode Line
Starting in Emacs 21, certain text properties are meaningful in the
mode line. The @code{face} property affects the appearance of text; the
@code{help-echo} property associate help strings with the text, and
@code{local-map} can make the text mouse-sensitive.
There are three ways to specify text properties for text in the mode
line:
@enumerate
@item
Put a string with the @code{local-map} property directly into the
mode-line data structure.
@item
Put a @code{local-map} property on a mode-line %-construct
such as @samp{%12b}; then the expansion of the %-construct
will have that same text property.
@item
Use a list containing @code{:eval @var{form}} in the mode-line data
structure, and make @var{form} evaluate to a string that has a
@code{local-map} property.
@end enumerate
You use the @code{local-map} property to specify a keymap. Like any
keymap, it can bind character keys and function keys; but that has no
effect, since is impossible to move point into the mode line, This
keymap can only take real effect for mouse clicks.
@node Header Lines
@subsection Window Header Lines
@cindex header line (of a window)
@cindex window header line
Starting in Emacs 21, a window can have a @dfn{header line} at the
top, just as it can have a mode line at the bottom. The header line
feature works just like the mode line feature, except that it's
controlled by different variables.
@tindex header-line-format
@defvar header-line-format
This variable, local in every buffer, specifies how to display the
header line, for windows displaying the buffer. The format of the value
is the same as for @code{mode-line-format} (@xref{Mode Line Data}).
@end defvar
@tindex default-header-line-format
@defvar default-header-line-format
This variable holds the default @code{header-line-format} for buffers
that do not override it. This is the same as @code{(default-value
'header-line-format)}.
It is normally @code{nil}, so that ordinary buffers have no header line.
@end defvar
@node Imenu
@section Imenu
@ -1390,9 +1503,10 @@ The value of @code{global-mode-string}. Currently, only
@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.
buffer index which lists the names and buffer positions of the
definitions, or portions of 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}:
@ -1413,9 +1527,10 @@ for this element should go in a submenu of the buffer index;
in the top level of the buffer index.
The second item in the list, @var{regexp}, is a regular expression
(@pxref{Regular Expressions}); wherever it matches, that is a definition
to mention in the buffer index. The third item, @var{subexp}, indicates
which subexpression in @var{regexp} matches the definition's name.
(@pxref{Regular Expressions}); anything in the buffer that it matches is
considered a 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:
@ -1483,7 +1598,7 @@ For example, Fortran mode uses it this way:
The @code{imenu-generic-expression} patterns can then use @samp{\\sw+}
instead of @samp{\\(\\sw\\|\\s_\\)+}. Note that this technique may be
inconvenient to use when the mode needs to limit the initial character
inconvenient when the mode needs to limit the initial character
of a name to a smaller set of characters than are allowed in the rest
of a name.
@ -1682,7 +1797,7 @@ expression or a function, as described above. The @sc{cdr},
highlighted (instead of the entire text that @var{matcher} matched).
@example
;; @r{Highlight the @samp{bar} in each occurrences of @samp{fubar},}
;; @r{Highlight the @samp{bar} in each occurrence of @samp{fubar},}
;; @r{using @code{font-lock-keyword-face}.}
("fu\\(bar\\)" . 1)
@end example
@ -1734,7 +1849,7 @@ Here are some examples of elements of this kind, and what they do:
;; @r{@code{foo-bar-face} should be a variable whose value is a face.}
("foo\\|bar" 0 foo-bar-face t)
;; @r{Highlight the first subexpression within each occurrences}
;; @r{Highlight the first subexpression within each occurrence}
;; @r{that the function @code{fubar-match} finds,}
;; @r{using the face which is the value of @code{fubar-face}.}
(fubar-match 1 fubar-face)

133
lispref/nonascii.texi
View file

@ -8,7 +8,7 @@
@cindex multibyte characters
@cindex non-ASCII characters
This chapter covers the special issues relating to non-@sc{ASCII}
This chapter covers the special issues relating to non-@sc{ascii}
characters and how they are stored in strings and buffers.
@menu
@ -40,8 +40,8 @@ attention to the difference.
@cindex unibyte text
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
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
character set by setting the variable @code{nonascii-insert-offset}).
@cindex leading code
@ -132,30 +132,30 @@ 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 be overridden automatically.
Converting unibyte text to multibyte text leaves @sc{ASCII} characters
unchanged, and likewise 128 through 159. It converts the non-@sc{ASCII}
Converting unibyte text to multibyte text leaves @sc{ascii} characters
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 (@pxref{Character
Sets}). For example, if @code{nonascii-insert-offset} is 2048, which is
@code{(- (make-char 'latin-iso8859-1) 128)}, then the unibyte
non-@sc{ASCII} characters correspond to Latin 1. If it is 2688, which
non-@sc{ascii} characters correspond to Latin 1. If it is 2688, which
is @code{(- (make-char 'greek-iso8859-7) 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} has a reasonable value, corresponding to
the beginning of some character set, this conversion is the inverse of
the other: converting unibyte text to multibyte and back to unibyte
reproduces the original unibyte text.
Converting multibyte text to unibyte is simpler: it discards all but
the low 8 bits of each character code. If @code{nonascii-insert-offset}
has a reasonable value, corresponding to the beginning of some character
set, this conversion is the inverse of the other: converting unibyte
text to multibyte and back to unibyte reproduces the original unibyte
text.
@defvar nonascii-insert-offset
@tindex nonascii-insert-offset
This variable specifies the amount to add to a non-@sc{ASCII} character
This variable specifies the amount to add to a non-@sc{ascii} character
when converting unibyte text to multibyte. It also applies when
@code{self-insert-command} inserts a character in the unibyte
non-@sc{ASCII} range, 128 through 255. However, the function
non-@sc{ascii} range, 128 through 255. However, the function
@code{insert-char} does not perform this conversion.
The right value to use to select character set @var{cs} is @code{(-
@ -245,7 +245,7 @@ codes. The valid character codes for unibyte representation range from
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 legitimate in multibyte text (though they can occur in ``raw
bytes''; @pxref{Explicit Encoding}). Only the @sc{ASCII} codes 0
bytes''; @pxref{Explicit Encoding}). Only the @sc{ascii} codes 0
through 127 are fully legitimate in both representations.
@defun char-valid-p charcode
@ -281,7 +281,7 @@ character sets, @code{chinese-big5-1} and @code{chinese-big5-2}.
@defun charsetp object
@tindex charsetp
Return @code{t} if @var{object} is a character set name symbol,
Returns @code{t} if @var{object} is a symbol that names a character set,
@code{nil} otherwise.
@end defun
@ -296,6 +296,15 @@ This function returns the name of the character set that @var{character}
belongs to.
@end defun
@defun charset-plist charset
@tindex charset-plist
This function returns the charset property list of the character set
@var{charset}. Although @var{charset} is a symbol, this is not the same
as the property list of that symbol. Charset properties are used for
special purposes within Emacs; for example, @code{x-charset-registry}
helps determine which fonts to use (@pxref{Font Selection}).
@end defun
@node Chars and Bytes
@section Characters and Bytes
@cindex bytes and characters
@ -304,7 +313,7 @@ belongs to.
@cindex dimension (of character set)
In multibyte representation, each character occupies one or more
bytes. Each character set has an @dfn{introduction sequence}, which is
normally one or two bytes long. (Exception: the @sc{ASCII} character
normally one or two bytes long. (Exception: the @sc{ascii} character
set has a zero-length introduction sequence.) The introduction sequence
is the beginning of the byte sequence for any character in the character
set. The rest of the character's bytes distinguish it from the other
@ -354,7 +363,7 @@ values is the character set's dimension.
@result{} (ascii 65)
@end example
Unibyte non-@sc{ASCII} characters are considered as part of
Unibyte non-@sc{ascii} characters are considered as part of
the @code{ascii} character set:
@example
@ -418,7 +427,7 @@ In two peculiar cases, the value includes the symbol @code{unknown}:
@itemize @bullet
@item
When a unibyte buffer contains non-@sc{ASCII} characters.
When a unibyte buffer contains non-@sc{ascii} characters.
@item
When a multibyte buffer contains invalid byte-sequences (raw bytes).
@ -445,10 +454,10 @@ for other purposes. Some coding systems specify their own particular
translation tables; there are also default translation tables which
apply to all other coding systems.
@defun make-translation-table translations
This function returns a translation table based on the arguments
@var{translations}. Each argument---each element of
@var{translations}---should be a list of the form @code{(@var{from}
@defun make-translation-table &rest translations
This function returns a translation table based on the argument
@var{translations}. Each element of
@var{translations} should be a list of the form @code{(@var{from}
. @var{to})}; this says to translate the character @var{from} into
@var{to}.
@ -495,7 +504,8 @@ subprocess or receives text from a subprocess, it normally performs
character code conversion and end-of-line conversion as specified
by a particular @dfn{coding system}.
How to define a coding system is an arcane matter, not yet documented.
How to define a coding system is an arcane matter, and is not
documented here.
@menu
* Coding System Basics::
@ -523,16 +533,15 @@ characters; for example, there are three coding systems for the Cyrillic
(Russian) alphabet: ISO, Alternativnyj, and KOI8.
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.
conversion, but some of them leave the choice unspecified---to be chosen
heuristically for each file, 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.
DOS convention is to use a carriage-return and a linefeed at the end of
a line. The Mac convention is to use just carriage-return.
@cindex base coding system
@cindex variant coding system
@ -610,10 +619,14 @@ to a subprocess.
@defvar save-buffer-coding-system
@tindex save-buffer-coding-system
This variable specifies the coding system for saving the buffer---but it
is not used for @code{write-region}. When saving the buffer asks the
user to specify a different coding system, and
@code{save-buffer-coding-system} was used, then it is updated to the
coding system that was specified.
is not used for @code{write-region}.
When a command to save the buffer starts out to use
@code{save-buffer-coding-system}, and that coding system cannot handle
the actual text in the buffer, the command asks the user to choose
another coding system. After that happens, the command also updates
@code{save-buffer-coding-system} to represent the coding system that the
user specified.
@end defvar
@defvar last-coding-system-used
@ -623,8 +636,8 @@ coding system name that was used. The explicit encoding and decoding
functions (@pxref{Explicit Encoding}) set it too.
@strong{Warning:} Since receiving subprocess output sets this variable,
it can change whenever Emacs waits; therefore, you should use copy the
value shortly after the function call which stores the value you are
it can change whenever Emacs waits; therefore, you should copy the
value shortly after the function call that stores the value you are
interested in.
@end defvar
@ -634,7 +647,7 @@ selections for the window system. @xref{Window System Selections}.
@node Lisp and Coding Systems
@subsection Coding Systems in Lisp
Here are Lisp facilities for working with coding systems;
Here are the Lisp facilities for working with coding systems:
@defun coding-system-list &optional base-only
@tindex coding-system-list
@ -711,7 +724,7 @@ decreasing priority. But if @var{highest} is non-@code{nil}, then the
return value is just one coding system, the one that is highest in
priority.
If the region contains only @sc{ASCII} characters, the value
If the region contains only @sc{ascii} characters, the value
is @code{undecided} or @code{(undecided)}.
@end defun
@ -788,13 +801,14 @@ expression that matches certain file names. The element applies to file
names that match @var{pattern}.
The @sc{cdr} of the element, @var{coding}, should be either a coding
system, a cons cell containing two coding systems, or a function symbol.
If @var{val} is a coding system, that coding system is used for both
reading the file and writing it. If @var{val} is a cons cell containing
two coding systems, its @sc{car} specifies the coding system for
decoding, and its @sc{cdr} specifies the coding system for encoding.
system, a cons cell containing two coding systems, or a function name (a
symbol with a function definition). If @var{coding} is a coding system,
that coding system is used for both reading the file and writing it. If
@var{coding} is a cons cell containing two coding systems, its @sc{car}
specifies the coding system for decoding, and its @sc{cdr} specifies the
coding system for encoding.
If @var{val} is a function symbol, the function must return a coding
If @var{coding} is a function name, the function must return a coding
system or a cons cell containing two coding systems. This value is used
as described above.
@end defvar
@ -810,8 +824,8 @@ coding systems used for I/O to the subprocess, but you can specify
other coding systems later using @code{set-process-coding-system}.
@end defvar
@strong{Warning:} Coding systems such as @code{undecided} which
determine the coding system from the data do not work entirely reliably
@strong{Warning:} Coding systems such as @code{undecided}, which
determine the coding system from the data, do not work entirely reliably
with asynchronous subprocess output. This is because Emacs handles
asynchronous subprocess output in batches, as it arrives. If the coding
system leaves the character code conversion unspecified, or leaves the
@ -859,13 +873,14 @@ for decoding (in case @var{operation} does decoding), and
@var{encoding-system} is the coding system for encoding (in case
@var{operation} does encoding).
The argument @var{operation} should be an Emacs I/O primitive:
The argument @var{operation} should be a symbol, one of
@code{insert-file-contents}, @code{write-region}, @code{call-process},
@code{call-process-region}, @code{start-process}, or
@code{open-network-stream}.
@code{open-network-stream}. These are the names of the Emacs I/O primitives
that can do coding system conversion.
The remaining arguments should be the same arguments that might be given
to that I/O primitive. Depending on which primitive, one of those
to that I/O primitive. Depending on the primitive, one of those
arguments is selected as the @dfn{target}. For example, if
@var{operation} does file I/O, whichever argument specifies the file
name is the target. For subprocess primitives, the process name is the
@ -1079,13 +1094,15 @@ that means do not encode terminal output.
@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. By ``binary file'' we mean a file of
literal byte values that are not necessary meant to be characters.
Emacs does no end-of-line conversion and no character code conversion
for a binary file. Meanwhile, when you create a new file which is
marked by its name as a ``text file'', Emacs uses DOS end-of-line
conversion.
On MS-DOS and Microsoft Windows, Emacs guesses the appropriate
end-of-line conversion for a file by looking at the file's name. This
feature classifies fils as @dfn{text files} and @dfn{binary files}. By
``binary file'' we mean a file of literal byte values that are not
necessarily meant to be characters; Emacs does no end-of-line conversion
and no character code conversion for them. On the other hand, the bytes
in a text file are intended to represent characters; when you create a
new file whose name implies that it is a text file, Emacs uses DOS
end-of-line conversion.
@defvar buffer-file-type
This variable, automatically buffer-local in each buffer, records the
@ -1108,7 +1125,7 @@ Each element has the form (@var{regexp} . @var{type}), where
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
When running on MS-DOS or MS-Windows, Emacs 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.
@ -1131,9 +1148,9 @@ from the file contents, in the usual Emacs fashion.
@section Input Methods
@cindex input methods
@dfn{Input methods} provide convenient ways of entering non-@sc{ASCII}
@dfn{Input methods} provide convenient ways of entering non-@sc{ascii}
characters from the keyboard. Unlike coding systems, which translate
non-@sc{ASCII} characters to and from encodings meant to be read by
non-@sc{ascii} characters to and from encodings meant to be read by
programs, input methods provide human-friendly commands. (@xref{Input
Methods,,, emacs, The GNU Emacs Manual}, for information on how users
use input methods to enter text.) How to define input methods is not

32
lispref/numbers.texi
View file

@ -40,14 +40,14 @@ minimum range is @minus{}134217728 to 134217727 (28 bits; i.e.,
-2**27
@end ifinfo
@tex
$-2^{27}$
@math{-2^{27}}
@end tex
to
@ifinfo
2**27 - 1),
@end ifinfo
@tex
$2^{27}-1$),
@math{2^{27}-1}),
@end tex
but some machines may provide a wider range. Many examples in this
chapter assume an integer has 28 bits.
@ -312,6 +312,8 @@ otherwise.
@defun max number-or-marker &rest numbers-or-markers
This function returns the largest of its arguments.
If any of the argument is floating-point, the value is returned
as floating point, even if it was given as an integer.
@example
(max 20)
@ -319,12 +321,14 @@ This function returns the largest of its arguments.
(max 1 2.5)
@result{} 2.5
(max 1 3 2.5)
@result{} 3
@result{} 3.0
@end example
@end defun
@defun min number-or-marker &rest numbers-or-markers
This function returns the smallest of its arguments.
If any of the argument is floating-point, the value is returned
as floating point, even if it was given as an integer.
@example
(min -4 1)
@ -958,14 +962,14 @@ The value of @code{(asin @var{arg})} is a number between
@minus{}pi/2
@end ifinfo
@tex
$-\pi/2$
@math{-\pi/2}
@end tex
and
@ifinfo
pi/2
@end ifinfo
@tex
$\pi/2$
@math{\pi/2}
@end tex
(inclusive) whose sine is @var{arg}; if, however, @var{arg}
is out of range (outside [-1, 1]), then the result is a NaN.
@ -977,7 +981,7 @@ The value of @code{(acos @var{arg})} is a number between 0 and
pi
@end ifinfo
@tex
$\pi$
@math{\pi}
@end tex
(inclusive) whose cosine is @var{arg}; if, however, @var{arg}
is out of range (outside [-1, 1]), then the result is a NaN.
@ -989,14 +993,14 @@ The value of @code{(atan @var{arg})} is a number between
@minus{}pi/2
@end ifinfo
@tex
$-\pi/2$
@math{-\pi/2}
@end tex
and
@ifinfo
pi/2
@end ifinfo
@tex
$\pi/2$
@math{\pi/2}
@end tex
(exclusive) whose tangent is @var{arg}.
@end defun
@ -1004,14 +1008,14 @@ $\pi/2$
@defun exp arg
This is the exponential function; it returns
@tex
$e$
@math{e}
@end tex
@ifinfo
@i{e}
@end ifinfo
to the power @var{arg}.
@tex
$e$
@math{e}
@end tex
@ifinfo
@i{e}
@ -1024,7 +1028,7 @@ logarithms.
This function returns the logarithm of @var{arg}, with base @var{base}.
If you don't specify @var{base}, the base
@tex
$e$
@math{e}
@end tex
@ifinfo
@i{e}
@ -1085,9 +1089,9 @@ first call to @code{(random)} after you start Emacs always returns
-1457731, and the second one always returns -7692030. This
repeatability is helpful for debugging.
If you want truly unpredictable random numbers, execute @code{(random
t)}. This chooses a new seed based on the current time of day and on
Emacs's process @sc{id} number.
If you want random numbers that don't always come out the same, execute
@code{(random t)}. This chooses a new seed based on the current time of
day and on Emacs's process @sc{id} number.
@defun random &optional limit
This function returns a pseudo-random integer. Repeated calls return a

161
lispref/objects.texi
View file

@ -25,7 +25,7 @@ but not for ``the'' type of an object.
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}, plus
@dfn{string}, @dfn{vector}, @dfn{subr}, and @dfn{byte-code function}, plus
several special types, such as @dfn{buffer}, that are related to
editing. (@xref{Editing Types}.)
@ -52,6 +52,7 @@ to use these types can be found in later chapters.
* Comments:: Comments and their formatting conventions.
* Programming Types:: Types found in all Lisp systems.
* Editing Types:: Types specific to Emacs.
* Circular Objects:: Read syntax for circular structure.
* Type Predicates:: Tests related to types.
* Equality Predicates:: Tests of equality between any two objects.
@end menu
@ -146,6 +147,7 @@ latter are unique to Emacs Lisp.
* Vector Type:: One-dimensional arrays.
* Char-Table Type:: One-dimensional sparse arrays indexed by characters.
* Bool-Vector Type:: One-dimensional arrays of @code{t} or @code{nil}.
* Hash Table Type:: Super-fast lookup tables.
* Function Type:: A piece of executable code you can call from elsewhere.
* Macro Type:: A method of expanding an expression into another
expression, more fundamental but less pretty.
@ -164,14 +166,14 @@ latter are unique to Emacs Lisp.
-2**27
@end ifinfo
@tex
$-2^{27}$
@math{-2^{27}}
@end tex
to
@ifinfo
2**27 - 1)
@end ifinfo
@tex
$2^{28}-1$)
@math{2^{28}-1})
@end tex
on most machines. (Some machines may provide a wider range.) It is
important to note that the Emacs Lisp arithmetic functions do not check
@ -187,7 +189,7 @@ leading @samp{+} or a final @samp{.}.
@group
-1 ; @r{The integer -1.}
1 ; @r{The integer 1.}
1. ; @r{Also The integer 1.}
1. ; @r{Also the integer 1.}
+1 ; @r{Also the integer 1.}
268435457 ; @r{Also the integer 1 on a 28-bit implementation.}
@end group
@ -212,7 +214,7 @@ number whose value is 1500. They are all equivalent.
@node Character Type
@subsection Character Type
@cindex @sc{ASCII} character codes
@cindex @sc{ascii} character codes
A @dfn{character} in Emacs Lisp is nothing more than an integer. In
other words, characters are represented by their character codes. For
@ -290,6 +292,7 @@ respectively. Thus,
?\r @result{} 13 ; @r{carriage return, @key{RET}, @kbd{C-m}}
?\e @result{} 27 ; @r{escape character, @key{ESC}, @kbd{C-[}}
?\\ @result{} 92 ; @r{backslash character, @kbd{\}}
?\d @result{} 127 ; @r{delete character, @key{DEL}}
@end example
@cindex escape sequence
@ -312,17 +315,17 @@ equivalent to @samp{?\^I} and to @samp{?\^i}:
@end example
In strings and buffers, the only control characters allowed are those
that exist in @sc{ASCII}; but for keyboard input purposes, you can turn
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
codes for these non-@sc{ascii} control characters include the
@tex
$2^{26}$
@math{2^{26}}
@end tex
@ifinfo
2**26
@end ifinfo
bit as well as the code for the corresponding non-control
character. Ordinary terminals have no way of generating non-@sc{ASCII}
character. Ordinary terminals have no way of generating non-@sc{ascii}
control characters, but you can generate them straightforwardly using X
and other window systems.
@ -349,7 +352,7 @@ people who read it.
A @dfn{meta character} is a character typed with the @key{META}
modifier key. The integer that represents such a character has the
@tex
$2^{27}$
@math{2^{27}}
@end tex
@ifinfo
2**27
@ -360,14 +363,14 @@ of basic character codes.
In a string, the
@tex
$2^{7}$
@math{2^{7}}
@end tex
@ifinfo
2**7
@end ifinfo
bit attached to an ASCII character indicates a meta character; thus, the
meta characters that can fit in a string have codes in the range from
128 to 255, and are the meta versions of the ordinary @sc{ASCII}
128 to 255, and are the meta versions of the ordinary @sc{ascii}
characters. (In Emacs versions 18 and older, this convention was used
for characters outside of strings as well.)
@ -379,11 +382,11 @@ or as @samp{?\M-\101}. Likewise, you can write @kbd{C-M-b} as
@samp{?\M-\C-b}, @samp{?\C-\M-b}, or @samp{?\M-\002}.
The case of a graphic character is indicated by its character code;
for example, @sc{ASCII} distinguishes between the characters @samp{a}
and @samp{A}. But @sc{ASCII} has no way to represent whether a control
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
@tex
$2^{25}$
@math{2^{25}}
@end tex
@ifinfo
2**25
@ -405,7 +408,7 @@ significant in these prefixes.) Thus, @samp{?\H-\M-\A-x} represents
@kbd{Alt-Hyper-Meta-x}.
@tex
Numerically, the
bit values are $2^{22}$ for alt, $2^{23}$ for super and $2^{24}$ for hyper.
bit values are @math{2^{22}} for alt, @math{2^{23}} for super and @math{2^{24}} for hyper.
@end tex
@ifinfo
Numerically, the
@ -420,9 +423,9 @@ character code in either octal or hex. To use octal, write a question
mark followed by a backslash and the octal character code (up to three
octal digits); thus, @samp{?\101} for the character @kbd{A},
@samp{?\001} for the character @kbd{C-a}, and @code{?\002} for the
character @kbd{C-b}. Although this syntax can represent any @sc{ASCII}
character @kbd{C-b}. Although this syntax can represent any @sc{ascii}
character, it is preferred only when the precise octal value is more
important than the @sc{ASCII} representation.
important than the @sc{ascii} representation.
@example
@group
@ -520,6 +523,11 @@ char-to-string ; @r{A symbol named @samp{char-to-string}.}
@end group
@end example
@cindex @samp{#:} read syntax
Normally the Lisp reader interns all symbols (@pxref{Creating
Symbols}). To prevent interning, you can write @samp{#:} before the
name of the symbol.
@node Sequence Type
@subsection Sequence Types
@ -559,7 +567,7 @@ same object, @code{nil}.
A @dfn{cons cell} is an object that consists of two slots, called the
@sc{car} slot and the @sc{cdr} slot. Each slot can @dfn{hold} or
@dfn{refer to} any Lisp object. We also say that the ``the @sc{car} of
@dfn{refer to} any Lisp object. We also say that ``the @sc{car} of
this cons cell is'' whatever object its @sc{car} slot currently holds,
and likewise for the @sc{cdr}.
@ -794,7 +802,8 @@ sets the variable @code{alist-of-colors} to an alist of three elements. In the
first element, @code{rose} is the key and @code{red} is the value.
@xref{Association Lists}, for a further explanation of alists and for
functions that work on alists.
functions that work on alists. @xref{Hash Tables}, for another kind of
lookup table, which is much faster for handling a large number of keys.
@node Array Type
@subsection Array Type
@ -884,9 +893,9 @@ but the newline is ignored if escaped."
@node Non-ASCII in Strings
@subsubsection Non-ASCII Characters in Strings
You can include a non-@sc{ASCII} international character in a string
You can include a non-@sc{ascii} international character in a string
constant by writing it literally. There are two text representations
for non-@sc{ASCII} characters in Emacs strings (and in buffers): unibyte
for non-@sc{ascii} characters in Emacs strings (and in buffers): unibyte
and multibyte. If the string constant is read from a multibyte source,
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
@ -895,7 +904,7 @@ unibyte source, then the character is read as unibyte and that makes the
string unibyte.
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
character code: use a hex escape, @samp{\x@var{nnnnnnn}}, with as many
digits as necessary. (Multibyte non-@sc{ASCII} character codes are all
greater than 256.) Any character which is not a valid hex digit
terminates this construct. If the next character in the string could be
@ -906,7 +915,7 @@ constant is just like backslash-newline; it does not contribute any
character to the string, but it does terminate the preceding hex escape.
Using a multibyte hex escape forces the string to multibyte. You can
represent a unibyte non-@sc{ASCII} character with its character code,
represent a unibyte non-@sc{ascii} character with its character code,
which must be in the range from 128 (0200 octal) to 255 (0377 octal).
This forces a unibyte string.
@ -925,16 +934,16 @@ description of the read syntax for characters.
However, not all of the characters you can write with backslash
escape-sequences are valid in strings. The only control characters that
a string can hold are the @sc{ASCII} control characters. Strings do not
distinguish case in @sc{ASCII} control characters.
a string can hold are the @sc{ascii} control characters. Strings do not
distinguish case in @sc{ascii} control characters.
Properly speaking, strings cannot hold meta characters; but when a
string is to be used as a key sequence, there is a special convention
that provides a way to represent meta versions of @sc{ASCII} characters in a
that provides a way to represent meta versions of @sc{ascii} characters in a
string. If you use the @samp{\M-} syntax to indicate a meta character
in a string constant, this sets the
@tex
$2^{7}$
@math{2^{7}}
@end tex
@ifinfo
2**7
@ -1043,7 +1052,7 @@ Syntax tables (@pxref{Syntax Tables}).
A @dfn{bool-vector} is a one-dimensional array of elements that
must be @code{t} or @code{nil}.
The printed representation of a Bool-vector is like a string, except
The printed representation of a bool-vector is like a string, except
that it begins with @samp{#&} followed by the length. The string
constant that follows actually specifies the contents of the bool-vector
as a bitmap---each ``character'' in the string contains 8 bits, which
@ -1063,6 +1072,19 @@ these extras really make no difference.
@result{} t
@end example
@node Hash Table Type
@subsection Hash Table Type
A hash table is a very fast kind of lookup table, somewhat like an
alist in that it maps keys to corresponding values, but much faster.
Hash tables are a new feature in Emacs 21; they have no read syntax, and
print using hash notation. @xref{Hash Tables}.
@example
(make-hash-table)
@result{} #<hash-table 'eql nil 0/65 0x83af980>
@end example
@node Function Type
@subsection Function Type
@ -1156,11 +1178,11 @@ opening @samp{[}.
@subsection Autoload Type
An @dfn{autoload object} is a list whose first element is the symbol
@code{autoload}. It is stored as the function definition of a symbol as
a placeholder for the real definition; it says that the real definition
is found in a file of Lisp code that should be loaded when necessary.
The autoload object contains the name of the file, plus some other
information about the real definition.
@code{autoload}. It is stored as the function definition of a symbol,
where it serves as a placeholder for the real definition. The autoload
object says that the real definition is found in a file of Lisp code
that should be loaded when necessary. It contains the name of the file,
plus some other information about the real definition.
After the file has been loaded, the symbol should have a new function
definition that is not an autoload object. The new definition is then
@ -1207,9 +1229,9 @@ buffer need not be displayed in any window.
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, 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.
existing buffer, altering the buffer's contents, whereas ``inserting''
text into a string requires concatenating substrings, and the result is
an entirely new string object.
Each buffer has a designated position called @dfn{point}
(@pxref{Positions}). At any time, one buffer is the @dfn{current
@ -1431,6 +1453,69 @@ positions.
@xref{Overlays}, for how to create and use overlays.
@node Circular Objects
@section Read Syntax for Circular Objects
@cindex circular structure, read syntax
@cindex shared structure, read syntax
@cindex @samp{#@var{n}=} read syntax
@cindex @samp{#@var{n}#} read syntax
In Emacs 21, to represent shared or circular structure within a
complex of Lisp objects, you can use the reader constructs
@samp{#@var{n}=} and @samp{#@var{n}#}.
Use @code{#@var{n}=} before an object to label it for later reference;
subsequently, you can use @code{#@var{n}#} to refer the same object in
another place. Here, @var{n} is some integer. For example, here is how
to make a list in which the first element recurs as the third element:
@example
(#1=(a) b #1#)
@end example
@noindent
This differs from ordinary syntax such as this
@example
((a) b (a))
@end example
@noindent
which would result in a list whose first and third elements
look alike but are not the same Lisp object. This shows the difference:
@example
(prog1 nil
(setq x '(#1=(a) b #1#)))
(eq (nth 0 x) (nth 2 x))
@result{} t
(setq x '((a) b (a)))
(eq (nth 0 x) (nth 2 x))
@result{} nil
@end example
You can also use the same syntax to make a circular structure, which
appears as an ``element'' within itself. Here is an example:
@example
#1=(a #1#)
@end example
@noindent
This makes a list whose second element is the list itself.
Here's how you can see that it really works:
@example
(prog1 nil
(setq x '#1=(a #1#)))
(eq x (cadr x))
@result{} t
@end example
The Lisp printer can produce this syntax to record circular and shared
structure in a Lisp object, if you bind the variable @code{print-circle}
to a non-@code{nil} value. @xref{Output Variables}.
@node Type Predicates
@section Type Predicates
@cindex predicates
@ -1764,7 +1849,7 @@ arguments to see if their elements are the same. So, if two objects are
Comparison of strings is case-sensitive, but does not take account of
text properties---it compares only the characters in the strings.
A unibyte string never equals a multibyte string unless the
contents are entirely @sc{ASCII} (@pxref{Text Representations}).
contents are entirely @sc{ascii} (@pxref{Text Representations}).
@example
@group

222
lispref/os.texi
View file

@ -15,7 +15,7 @@ and flow control.
pertaining to the terminal and the screen.
@menu
* Starting Up:: Customizing Emacs start-up processing.
* Starting Up:: Customizing Emacs startup processing.
* Getting Out:: How exiting works (permanent or temporary).
* System Environment:: Distinguish the name and kind of system.
* User Identification:: Finding the name and user id of the user.
@ -25,6 +25,7 @@ pertaining to the terminal and the screen.
* Timers:: Setting a timer to call a function at a certain time.
* Terminal Input:: Recording terminal input for debugging.
* Terminal Output:: Recording terminal output for debugging.
* Sound Output:: Playing sounds on the computer's speaker.
* Special Keysyms:: Defining system-specific key symbols for X windows.
* Flow Control:: How to turn output flow control on or off.
* Batch Mode:: Running Emacs without terminal interaction.
@ -37,17 +38,17 @@ pertaining to the terminal and the screen.
can customize these actions.
@menu
* Start-up Summary:: Sequence of actions Emacs performs at start-up.
* Startup Summary:: Sequence of actions Emacs performs at startup.
* Init File:: Details on reading the init file (@file{.emacs}).
* Terminal-Specific:: How the terminal-specific Lisp file is read.
* Command Line Arguments:: How command line arguments are processed,
* Command-Line Arguments:: How command-line arguments are processed,
and how you can customize them.
@end menu
@node Start-up Summary
@subsection Summary: Sequence of Actions at Start Up
@node Startup Summary
@subsection Summary: Sequence of Actions at Startup
@cindex initialization
@cindex start up of Emacs
@cindex startup of Emacs
@cindex @file{startup.el}
The order of operations performed (in @file{startup.el}) by Emacs when
@ -86,7 +87,7 @@ It loads the library @file{site-start}, unless the option
@item
It loads the file @file{~/.emacs}, unless @samp{-q} or @samp{-batch} was
specified on the command line. The @samp{-u} option can specify another
user name whose home directory should be used instead of @file{~}.
user whose home directory should be used instead of @file{~}.
@item
It loads the library @file{default}, unless @code{inhibit-default-init}
@ -127,7 +128,7 @@ It runs @code{window-setup-hook}. @xref{Window Systems}.
@item
It displays copyleft, nonwarranty, and basic use information, provided
there were no remaining command line arguments (a few steps above),
there were no remaining command-line arguments (a few steps above),
the value of @code{inhibit-startup-message} is @code{nil}, and the
buffer is still empty.
@end enumerate
@ -170,12 +171,12 @@ message for someone else.
@cindex @file{.emacs}
When you start Emacs, it normally attempts to load the file
@file{.emacs} from your home directory. This file, if it exists, must
contain Lisp code. It is called your @dfn{init file}. The command line
switches @samp{-q} and @samp{-u} affect the use of the init file;
@samp{-q} says not to load an init file, and @samp{-u} says to load a
specified user's init file instead of yours. @xref{Entering Emacs,,,
emacs, The GNU Emacs Manual}.
@file{.emacs} from your home directory. This file is called your
@dfn{init file}. If it exists, it must contain Lisp code. The
command-line switches @samp{-q} and @samp{-u} affect the use of the init
file; @samp{-q} says not to load an init file, and @samp{-u} says to
load a specified user's init file instead of yours. @xref{Entering
Emacs,,, emacs, The GNU Emacs Manual}.
@cindex default init file
A site may have a @dfn{default init file}, which is the library named
@ -200,9 +201,8 @@ Emacs.
@end defvar
If there is a great deal of code in your @file{.emacs} file, you
should move it into another file named @file{@var{something}.el},
byte-compile it (@pxref{Byte Compilation}), and make your @file{.emacs}
file load the other file using @code{load} (@pxref{Loading}).
can make it load faster by renaming it to @file{.emacs.el}
and then byte-compiling it (@pxref{Byte Compilation}).
@xref{Init File Examples,,, emacs, The GNU Emacs Manual}, for
examples of how to make various commonly desired customizations in your
@ -234,7 +234,8 @@ before the terminal-specific initialization.
Each terminal type can have its own Lisp library that Emacs loads when
run on that type of terminal. The library's name is constructed by
concatenating the value of the variable @code{term-file-prefix} and the
terminal type. Normally, @code{term-file-prefix} has the value
terminal type (specified by the environment variable @code{TERM}).
Normally, @code{term-file-prefix} has the value
@code{"term/"}; changing this is not recommended. Emacs finds the file
in the normal manner, by searching the @code{load-path} directories, and
trying the @samp{.elc} and @samp{.el} suffixes.
@ -279,6 +280,9 @@ You may set the @code{term-file-prefix} variable to @code{nil} in your
@file{.emacs} file if you do not wish to load the
terminal-initialization file. To do this, put the following in
your @file{.emacs} file: @code{(setq term-file-prefix nil)}.
On MS-DOS, if the environment variable @code{TERM} is not set, Emacs
uses @samp{internal} as the terminal type.
@end defvar
@defvar term-setup-hook
@ -293,27 +297,27 @@ terminal-specific file.
See @code{window-setup-hook} in @ref{Window Systems}, for a related
feature.
@node Command Line Arguments
@subsection Command Line Arguments
@cindex command line arguments
@node Command-Line Arguments
@subsection Command-Line Arguments
@cindex command-line arguments
You can use command line arguments to request various actions when you
You can use command-line arguments to request various actions when you
start Emacs. Since you do not need to start Emacs more than once per
day, and will often leave your Emacs session running longer than that,
command line arguments are hardly ever used. As a practical matter, it
command-line arguments are hardly ever used. As a practical matter, it
is best to avoid making the habit of using them, since this habit would
encourage you to kill and restart Emacs unnecessarily often. These
options exist for two reasons: to be compatible with other editors (for
invocation by other programs) and to enable shell scripts to run
specific Lisp programs.
This section describes how Emacs processes command line arguments,
This section describes how Emacs processes command-line arguments,
and how you can customize them.
@ignore
(Note that some other editors require you to start afresh each time
you want to edit a file. With this kind of editor, you will probably
specify the file as a command line argument. The recommended way to
specify the file as a command-line argument. The recommended way to
use GNU Emacs is to start it only once, just after you log in, and do
all your editing in the same Emacs process. Each time you want to edit
a different file, you visit it with the existing Emacs, which eventually
@ -333,19 +337,19 @@ processed.
If you redump Emacs by calling @code{dump-emacs}, you may wish to set
this variable to @code{nil} first in order to cause the new dumped Emacs
to process its new command line arguments.
to process its new command-line arguments.
@end defvar
@defvar command-switch-alist
@cindex switches on command line
@cindex options on command line
@cindex command line options
@cindex command-line options
The value of this variable is an alist of user-defined command-line
options and associated handler functions. This variable exists so you
can add elements to it.
A @dfn{command line option} is an argument on the command line of the
form:
A @dfn{command-line option} is an argument on the command line, which
has the form:
@example
-@var{option}
@ -357,8 +361,10 @@ The elements of the @code{command-switch-alist} look like this:
(@var{option} . @var{handler-function})
@end example
The @var{handler-function} is called to handle @var{option} and receives
the option name as its sole argument.
The @sc{car}, @var{option}, is a string, the name of a command-line
option (not including the initial hyphen). The @var{handler-function}
is called to handle @var{option}, and receives the option name as its
sole argument.
In some cases, the option is followed in the command line by an
argument. In these cases, the @var{handler-function} can find all the
@ -366,14 +372,14 @@ remaining command-line arguments in the variable
@code{command-line-args-left}. (The entire list of command-line
arguments is in @code{command-line-args}.)
The command line arguments are parsed by the @code{command-line-1}
The command-line arguments are parsed by the @code{command-line-1}
function in the @file{startup.el} file. See also @ref{Command
Switches, , Command Line Switches and Arguments, emacs, The GNU Emacs
Manual}.
@end defvar
@defvar command-line-args
The value of this variable is the list of command line arguments passed
The value of this variable is the list of command-line arguments passed
to Emacs.
@end defvar
@ -436,10 +442,10 @@ input) can read them.
@end defun
All the information in the Emacs process, aside from files that have
been saved, is lost when the Emacs is killed. Because killing Emacs
inadvertently can lose a lot of work, Emacs queries for confirmation
before actually terminating if you have buffers that need saving or
subprocesses that are running. This is done in the function
been saved, is lost when the Emacs process is killed. Because killing
Emacs inadvertently can lose a lot of work, Emacs queries for
confirmation before actually terminating if you have buffers that need
saving or subprocesses that are running. This is done in the function
@code{save-buffers-kill-emacs}.
@defvar kill-emacs-query-functions
@ -475,7 +481,7 @@ subprocess of Emacs. Then you would exit the shell to return to Emacs.
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.
a window system (X Windows or MS Windows).
@defun suspend-emacs string
This function stops Emacs and returns control to the superior process.
@ -545,11 +551,12 @@ Resumed!
@end defun
@defvar suspend-hook
This variable is a normal hook run before suspending.
This variable is a normal hook that Emacs runs before suspending.
@end defvar
@defvar suspend-resume-hook
This variable is a normal hook run after suspending.
This variable is a normal hook that Emacs runs on resuming
after a suspension.
@end defvar
@node System Environment
@ -598,7 +605,9 @@ Hewlett-Packard HPUX operating system.
Silicon Graphics Irix system.
@item ms-dos
Microsoft MS-DOS ``operating system.''
Microsoft MS-DOS ``operating system.'' Emacs compiled with DJGPP for
MS-DOS binds @code{system-type} to @code{ms-dos} even when you run it on
MS-Windows.
@item next-mach
NeXT Mach-based system.
@ -616,7 +625,8 @@ AT&T System V.
VAX VMS.
@item windows-nt
Microsoft windows NT.
Microsoft windows NT. The same executable supports Windows 9X, but the
value of @code{system-type} is @code{windows-nt} in either case.
@item xenix
SCO Xenix 386.
@ -710,7 +720,7 @@ process-environment
This variable holds a string which says which character separates
directories in a search path (as found in an environment variable). Its
value is @code{":"} for Unix and GNU systems, and @code{";"} for MS-DOS
and Windows NT.
and MS-Windows.
@end defvar
@defvar invocation-name
@ -770,10 +780,11 @@ in the system's terminal driver, before Emacs was started.
@defun setprv privilege-name &optional setp getprv
This function sets or resets a VMS privilege. (It does not exist on
Unix.) The first arg is the privilege name, as a string. The second
argument, @var{setp}, is @code{t} or @code{nil}, indicating whether the
privilege is to be turned on or off. Its default is @code{nil}. The
function returns @code{t} if successful, @code{nil} otherwise.
other systems.) The first argument is the privilege name, as a string.
The second argument, @var{setp}, is @code{t} or @code{nil}, indicating
whether the privilege is to be turned on or off. Its default is
@code{nil}. The function returns @code{t} if successful, @code{nil}
otherwise.
If the third argument, @var{getprv}, is non-@code{nil}, @code{setprv}
does not change the privilege, but returns @code{t} or @code{nil}
@ -785,7 +796,7 @@ indicating whether the privilege is currently enabled.
@defvar init-file-user
This variable says which user's init files should be used by Emacs---or
@code{nil} if none. The value reflects command line options such as
@code{nil} if none. The value reflects command-line options such as
@samp{-q} or @samp{-u @var{user}}.
Lisp packages that load files of customizations, or any other sort of
@ -830,8 +841,9 @@ environment variables @code{LOGNAME} and @code{USER}.
@defun user-full-name &optional uid
This function returns the full name of the logged-in user---or the value
of the environment variables @code{NAME}, if that is set.
of the environment variable @code{NAME}, if that is set.
@c "Bil" is the correct spelling.
@example
@group
(user-full-name)
@ -907,7 +919,7 @@ two elements are integers. Thus, you can use times obtained from
This function returns the system's time value as a list of three
integers: @code{(@var{high} @var{low} @var{microsec})}. The integers
@var{high} and @var{low} combine to give the number of seconds since
0:00 January 1, 1970, which is
0:00 January 1, 1970 (local time), which is
@ifinfo
@var{high} * 2**16 + @var{low}.
@end ifinfo
@ -916,8 +928,8 @@ $high*2^{16}+low$.
@end tex
The third element, @var{microsec}, gives the microseconds since the
start of the current second (or 0 for systems that return time only on
the resolution of a second).
start of the current second (or 0 for systems that return time with
the resolution of only one second).
The first two elements can be compared with file time values such as you
get with the function @code{file-attributes}. @xref{File Attributes}.
@ -931,7 +943,7 @@ in.
The value has the form @code{(@var{offset} @var{name})}. Here
@var{offset} is an integer giving the number of seconds ahead of UTC
(east of Greenwich). A negative value means west of Greenwich. The
second element, @var{name} is a string giving the name of the time
second element, @var{name}, is a string giving the name of the time
zone. Both elements change when daylight savings time begins or ends;
if the user has specified a time zone that does not use a seasonal time
adjustment, then the value is constant through time.
@ -998,7 +1010,7 @@ This is a synonym for @samp{%b}.
@item %H
This stands for the hour (00-23).
@item %I
This stands for the hour (00-12).
This stands for the hour (01-12).
@item %j
This stands for the day of the year (001-366).
@item %k
@ -1018,7 +1030,7 @@ This is a synonym for @samp{%I:%M:%S %p}.
@item %R
This is a synonym for @samp{%H:%M}.
@item %S
This stands for the seconds (00-60).
This stands for the seconds (00-59).
@item %t
This stands for a tab character.
@item %T
@ -1068,9 +1080,9 @@ return value is a list of nine elements, as follows:
Here is what the elements mean:
@table @var
@item sec
@item seconds
The number of seconds past the minute, as an integer between 0 and 59.
@item minute
@item minutes
The number of minutes past the hour, as an integer between 0 and 59.
@item hour
The hour of the day, as an integer between 0 and 23.
@ -1099,9 +1111,9 @@ This function is the inverse of @code{decode-time}. It converts seven
items of calendrical data into a time value. For the meanings of the
arguments, see the table above under @code{decode-time}.
Year numbers less than 100 are treated just like other year numbers. If
you want them to stand for years above 1900, you must alter them yourself
before you call @code{encode-time}.
Year numbers less than 100 are not treated specially. If you want them
to stand for years above 1900, you must alter them yourself before you
call @code{encode-time}.
The optional argument @var{zone} defaults to the current time zone and
its daylight savings time rules. If specified, it can be either a list
@ -1121,7 +1133,7 @@ feature makes it possible to use the elements of a list returned by
@end example
You can perform simple date arithmetic by using out-of-range values for
the @var{sec}, @var{minute}, @var{hour}, @var{day}, and @var{month}
the @var{seconds}, @var{minutes}, @var{hour}, @var{day}, and @var{month}
arguments; for example, day 0 means the day preceding the given month.
The operating system puts limits on the range of possible time values;
@ -1175,6 +1187,9 @@ denotes 65 seconds from now.
denotes exactly 103 months, 123 days, and 10862 seconds from now.
@end table
For relative time values, Emacs considers a month to be exactly thirty
days, and a year to be exactly 365.25 days.
If @var{time} is a number (integer or floating point), that specifies a
relative time measured in seconds.
@ -1236,10 +1251,10 @@ can use in calling @code{cancel-timer} (see below).
Emacs becomes ``idle'' when it starts waiting for user input, and it
remains idle until the user provides some input. If a timer is set for
five seconds of idleness, it runs approximately five seconds after Emacs
first became idle. Even if its @var{repeat} is true, this timer will
not run again as long as Emacs remains idle, because the duration of
idleness will continue to increase and will not go down to five seconds
again.
first becomes idle. Even if @var{repeat} is non-@code{nil}, this timer
will not run again as long as Emacs remains idle, because the duration
of idleness will continue to increase and will not go down to five
seconds again.
Emacs can do various things while idle: garbage collect, autosave or
handle data from a subprocess. But these interludes during idleness do
@ -1247,7 +1262,7 @@ 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.
minutes, and 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
@ -1284,7 +1299,7 @@ functions.
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. The default setting is
system dependent. Some systems always use @sc{cbreak} mode regardless
system-dependent. Some systems always use @sc{cbreak} mode regardless
of what is specified.
When Emacs communicates directly with X, it ignores this argument and
@ -1314,7 +1329,7 @@ Emacs is currently using.
@c Emacs 19 feature
@defun current-input-mode
This function returns current mode for reading keyboard input. It
This function returns the current mode for reading keyboard input. It
returns a list, corresponding to the arguments of @code{set-input-mode},
of the form @code{(@var{interrupt} @var{flow} @var{meta} @var{quit})} in
which:
@ -1379,10 +1394,10 @@ This variable is the translate table for keyboard characters. It lets
you reshuffle the keys on the keyboard without changing any command
bindings. Its value is normally a char-table, or else @code{nil}.
If @code{keyboard-translate-table} is a char-table, then each character
read from the keyboard is looked up in this character. If the value
found there is non-@code{nil}, then it is used instead of the
actual input character.
If @code{keyboard-translate-table} is a char-table
(@pxref{Char-Tables}), then each character read from the keyboard is
looked up in this char-table. If the value found there is
non-@code{nil}, then it is used instead of the actual input character.
In the example below, we set @code{keyboard-translate-table} to a
char-table. Then we fill it in to swap the characters @kbd{C-s} and
@ -1573,7 +1588,7 @@ trigger an Emacs bug, for the sake of a bug report.
@section Terminal Output
@cindex terminal output
The terminal output functions send output to the terminal or keep
The terminal output functions send output to the terminal, or keep
track of output sent to the terminal. The variable @code{baud-rate}
tells you what Emacs thinks is the output speed of the terminal.
@ -1607,8 +1622,8 @@ This function sends @var{string} to the terminal without alteration.
Control characters in @var{string} have terminal-dependent effects.
One use of this function is to define function keys on terminals that
have downloadable function key definitions. For example, this is how on
certain terminals to define function key 4 to move forward four
have downloadable function key definitions. For example, this is how (on
certain terminals) to define function key 4 to move forward four
characters (by transmitting the characters @kbd{C-u C-f} to the
computer):
@ -1641,6 +1656,51 @@ See also @code{open-dribble-file} in @ref{Terminal Input}.
@end example
@end deffn
@node Sound Output
@section Sound Output
@cindex sound
To play sound using Emacs, use the function @code{play-sound}. Only
certain systems are supported; if you call @code{play-sound} on a system
which cannot really do the job, it gives an error. Emacs version 20 and
earlier did not support sound at all.
The sound must be stored as a file in RIFF-WAVE format (@samp{.wav})
or Sun Audio format (@samp{.au}).
@tindex play-sound
@defun play-sound sound
This function plays a specified sound. The argument, @var{sound}, has
the form @code{(sound @var{properties}...)}, where the @var{properties}
consist of alternating keywords (particular symbols recognized
specially) and values corresponding to them.
Here is a table of the keywords that are currently meaningful in
@var{sound}, and their meanings:
@table @code
@item :file @var{file}
This specifies the file containing the sound to play.
If the file name is not absolute, it is expanded against
the directory @code{data-directory}.
@item :volume @var{volume}
This specifies how loud to play the sound. It should be a number in the
range of 0 to 1. The default is to use whatever volume has been
specified before.
@end table
Before actually playing the sound, @code{play-sound}
calls the functions in the list @code{play-sound-functions}.
Each function is called with one argument, @var{sound}.
@end defun
@tindex play-sound-functions
@defvar play-sound-functions
A list of functions to be called before playing a sound. Each function
is called with one argument, a property list that describes the sound.
@end defvar
@node Special Keysyms
@section System-Specific X11 Keysyms
@ -1649,7 +1709,7 @@ To define system-specific X11 keysyms, set the variable
@defvar system-key-alist
This variable's value should be an alist with one element for each
system-specific keysym. An element has this form: @code{(@var{code}
system-specific keysym. Each element has the form @code{(@var{code}
. @var{symbol})}, where @var{code} is the numeric keysym code (not
including the ``vendor specific'' bit,
@ifinfo
@ -1660,8 +1720,8 @@ $-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
For example @code{(168 . mute-acute)} defines a system-specific key (used
by HP X servers) whose numeric code is
@ifinfo
-2**28
@end ifinfo
@ -1694,7 +1754,7 @@ entries and DEC terminal concentrators, see @file{emacs/etc/TERMS}.
@code{C-s} and @kbd{C-q} for flow control. Therefore, the choice of
@kbd{C-s} and @kbd{C-q} as command characters for searching and quoting
was natural and uncontroversial. With so many commands needing key
assignments, of course we assigned meanings to nearly all @sc{ASCII}
assignments, of course we assigned meanings to nearly all @sc{ascii}
control characters.
Later, some terminals were introduced which required these characters
@ -1769,7 +1829,7 @@ speed when calculating the padding needed. @xref{Terminal Output}.
@cindex batch mode
@cindex noninteractive use
The command line option @samp{-batch} causes Emacs to run
The command-line option @samp{-batch} causes Emacs to run
noninteractively. In this mode, Emacs does not read commands from the
terminal, it does not alter the terminal modes, and it does not expect
to be outputting to an erasable screen. The idea is that you specify
@ -1779,7 +1839,7 @@ loads the library named @var{file}, and @samp{-f @var{function}}, which
calls @var{function} with no arguments.
Any Lisp program output that would normally go to the echo area,
either using @code{message} or using @code{prin1}, etc., with @code{t}
either using @code{message}, or using @code{prin1}, etc., with @code{t}
as the stream, goes instead to Emacs's standard error descriptor when
in batch mode. Thus, Emacs behaves much like a noninteractive
application program. (The echo area output that Emacs itself normally

41
lispref/positions.texi
View file

@ -42,10 +42,10 @@ the character that immediately follows point; point is actually before
the character on which the cursor sits.
@cindex point with narrowing
The value of point is a number between 1 and the buffer size plus 1.
If narrowing is in effect (@pxref{Narrowing}), then point is constrained
to fall within the accessible portion of the buffer (possibly at one end
of it).
The value of point is a number no less than 1, and no greater than the
buffer size plus 1. If narrowing is in effect (@pxref{Narrowing}), then
point is constrained to fall within the accessible portion of the buffer
(possibly at one end of it).
Each buffer has its own value of point, which is independent of the
value of point in other buffers. Each window also has a value of point,
@ -81,7 +81,7 @@ is the position of the start of the region that you narrowed to.
This function returns the maximum accessible value of point in the
current buffer. This is @code{(1+ (buffer-size))}, unless narrowing is
in effect, in which case it is the position of the end of the region
that you narrowed to. (@pxref{Narrowing}).
that you narrowed to. (@xref{Narrowing}.)
@end defun
@defun buffer-end flag
@ -89,11 +89,14 @@ This function returns @code{(point-min)} if @var{flag} is less than 1,
@code{(point-max)} otherwise. The argument @var{flag} must be a number.
@end defun
@defun buffer-size
@defun buffer-size &optional buffer
This function returns the total number of characters in the current
buffer. In the absence of any narrowing (@pxref{Narrowing}),
@code{point-max} returns a value one larger than this.
If you specify a buffer, @var{buffer}, then the value is the
size of @var{buffer}.
@example
@group
(buffer-size)
@ -190,6 +193,9 @@ the buffer boundary (except perhaps after the last word), the value is
@code{t}. Otherwise, the return value is @code{nil} and point stops
at the buffer boundary.
In the minibuffer, the end of the prompt always acts as a word boundary,
regardless of what characters appear before and after it.
In an interactive call, @var{count} is set to the numeric prefix
argument.
@end deffn
@ -241,7 +247,8 @@ they set the mark and display messages in the echo area.
This function moves point to the beginning of the buffer (or the limits
of the accessible portion, when narrowing is in effect), setting the
mark at the previous position. If @var{n} is non-@code{nil}, then it
puts point @var{n} tenths of the way from the beginning of the buffer.
puts point @var{n} tenths of the way from the beginning of the
accessible portion of the buffer.
In an interactive call, @var{n} is the numeric prefix argument,
if provided; otherwise @var{n} defaults to @code{nil}.
@ -250,10 +257,11 @@ if provided; otherwise @var{n} defaults to @code{nil}.
@end deffn
@deffn Command end-of-buffer &optional n
This function moves point to the end of the buffer (or the limits of
the accessible portion, when narrowing is in effect), setting the mark
at the previous position. If @var{n} is non-@code{nil}, then it puts
point @var{n} tenths of the way from the end of the buffer.
This function moves point to the end of the buffer (or the limits of the
accessible portion, when narrowing is in effect), setting the mark at
the previous position. If @var{n} is non-@code{nil}, then it puts point
@var{n} tenths of the way from the end of the accessible portion of the
buffer.
In an interactive call, @var{n} is the numeric prefix argument,
if provided; otherwise @var{n} defaults to @code{nil}.
@ -308,6 +316,9 @@ argument @var{count} not @code{nil} or 1, it moves forward
If this function reaches the end of the buffer (or of the accessible
portion, if narrowing is in effect), it positions point there. No error
is signaled.
As a special feature, in the minibuffer, this command will not
move back into the prompt, if it starts from after the prompt.
@end deffn
@defun line-beginning-position &optional count
@ -584,7 +595,7 @@ expressions (also called @dfn{sexps} in connection with moving across
them in Emacs). The syntax table controls how these functions interpret
various characters; see @ref{Syntax Tables}. @xref{Parsing
Expressions}, for lower-level primitives for scanning sexps or parts of
sexps. For user-level commands, see @ref{Lists Commands,,, emacs, GNU
sexps. For user-level commands, see @ref{Lists Commands,,, emacs, The GNU
Emacs Manual}.
@deffn Command forward-list arg
@ -725,9 +736,9 @@ is zero or less.
It is often useful to move point ``temporarily'' within a localized
portion of the program, or to switch buffers temporarily. This is
called an @dfn{excursion}, and it is done with the @code{save-excursion}
special form. This construct saves the current buffer and its values of
point and the mark so they can be restored after the completion of the
excursion.
special form. This construct initially remembers the identity of the
current buffer, and its values of point and the mark, and restores them
after the completion of the excursion.
The forms for saving and restoring the configuration of windows are
described elsewhere (see @ref{Window Configurations}, and @pxref{Frame

75
lispref/processes.texi
View file

@ -58,7 +58,7 @@ The other two, @code{call-process} and @code{call-process-region},
create a synchronous process and do not return a process object
(@pxref{Synchronous Processes}).
Synchronous and asynchronous processes are explained in following
Synchronous and asynchronous processes are explained in the following
sections. Since the three functions are all called in a similar
fashion, their common arguments are described here.
@ -108,7 +108,7 @@ Environment}.
@defvar exec-directory
@pindex movemail
The value of this variable is the name of a directory (a string) that
The value of this variable is a string, the name of a directory that
contains programs that come with GNU Emacs, programs intended for Emacs
to invoke. The program @code{movemail} is an example of such a program;
Rmail uses it to fetch new mail from an inbox.
@ -130,7 +130,7 @@ file name.
@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
that 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
@ -143,16 +143,18 @@ 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.
function is designed to work with the syntax of your system's standard
shell; if you use an unusual shell, you will need to redefine this
function.
@example
;; @r{This example shows the behavior on GNU and Unix systems.}
(shell-quote-argument "foo > bar")
@result{} "foo\\ \\>\\ bar"
;; @r{This example shows the behavior on MS-DOS and MS-Windows systems.}
(shell-quote-argument "foo > bar")
@result{} "\"foo > bar\""
@end example
Here's an example of using @code{shell-quote-argument} to construct
@ -171,18 +173,20 @@ a shell command:
@cindex synchronous subprocess
After a @dfn{synchronous process} is created, Emacs waits for the
process to terminate before continuing. Starting Dired is an example of
this: it runs @code{ls} in a synchronous process, then modifies the
output slightly. Because the process is synchronous, the entire
directory listing arrives in the buffer before Emacs tries to do
anything with it.
process to terminate before continuing. Starting Dired on GNU or
Unix@footnote{On other systems, Emacs uses a Lisp emulation of
@code{ls}; see @ref{Contents of Directories}.} is an example of this: it
runs @code{ls} in a synchronous process, then modifies the output
slightly. Because the process is synchronous, the entire directory
listing arrives in the buffer before Emacs tries to do anything with it.
While Emacs waits for the synchronous subprocess to terminate, the
user can quit by typing @kbd{C-g}. The first @kbd{C-g} tries to kill
the subprocess with a @code{SIGINT} signal; but it waits until the
subprocess actually terminates before quitting. If during that time the
user types another @kbd{C-g}, that kills the subprocess instantly with
@code{SIGKILL} and quits immediately. @xref{Quitting}.
@code{SIGKILL} and quits immediately (except on MS-DOS, where killing
other processes doesn't work). @xref{Quitting}.
The synchronous subprocess functions return an indication of how the
process terminated.
@ -197,7 +201,7 @@ This function calls @var{program} in a separate process and waits for
it to finish.
The standard input for the process comes from file @var{infile} if
@var{infile} is not @code{nil}, and from @file{/dev/null} otherwise.
@var{infile} is not @code{nil}, and from the null device otherwise.
The argument @var{destination} says where to put the process output.
Here are the possibilities:
@ -216,7 +220,7 @@ Insert the output in the current buffer, before point.
Discard the output.
@item 0
Discard the output, and return immediately without waiting
Discard the output, and return @code{nil} immediately without waiting
for the subprocess to finish.
In this case, the process is not truly synchronous, since it can run in
@ -224,6 +228,9 @@ parallel with Emacs; but you can think of it as synchronous in that
Emacs is essentially finished with the subprocess as soon as this
function returns.
MS-DOS doesn't support asynchronous subprocesses, so this option doesn't
work there.
@item @code{(@var{real-destination} @var{error-destination})}
Keep the standard output stream separate from the standard error stream;
deal with the ordinary output as specified by @var{real-destination},
@ -242,11 +249,12 @@ If @var{display} is non-@code{nil}, then @code{call-process} redisplays
the buffer as output is inserted. (However, if the coding system chosen
for decoding output is @code{undecided}, meaning deduce the encoding
from the actual data, then redisplay sometimes cannot continue once
non-@sc{ASCII} characters are encountered. There are fundamental
reasons why it is hard to fix this.) Otherwise the function
@code{call-process} does no redisplay, and the results become visible on
the screen only when Emacs redisplays that buffer in the normal course
of events.
non-@sc{ascii} characters are encountered. There are fundamental
reasons why it is hard to fix this; see @ref{Output from Processes}.)
Otherwise the function @code{call-process} does no redisplay, and the
results become visible on the screen only when Emacs redisplays that
buffer in the normal course of events.
The remaining arguments, @var{args}, are strings that specify command
line arguments for the program.
@ -262,7 +270,7 @@ In the examples below, the buffer @samp{foo} is current.
@smallexample
@group
(call-process "pwd" nil t)
@result{} nil
@result{} 0
---------- Buffer: foo ----------
/usr/user/lewis/manual
@ -271,7 +279,7 @@ In the examples below, the buffer @samp{foo} is current.
@group
(call-process "grep" nil "bar" nil "lewis" "/etc/passwd")
@result{} nil
@result{} 0
---------- Buffer: bar ----------
lewis:5LTsHm66CSWKg:398:21:Bil Lewis:/user/lewis:/bin/csh
@ -294,7 +302,7 @@ be found in the definition of @code{insert-directory}:
@end defun
@defun call-process-region start end program &optional delete destination display &rest args
This function sends the text between @var{start} to @var{end} as
This function sends the text from @var{start} to @var{end} as
standard input to a process running @var{program}. It deletes the text
sent if @var{delete} is non-@code{nil}; this is useful when
@var{destination} is @code{t}, to insert the output in the current
@ -305,7 +313,8 @@ with the output from the subprocess, and whether to update the display
as it comes in. For details, see the description of
@code{call-process}, above. If @var{destination} is the integer 0,
@code{call-process-region} discards the output and returns @code{nil}
immediately, without waiting for the subprocess to finish.
immediately, without waiting for the subprocess to finish (this only
works if asynchronous subprocess are supported).
The remaining arguments, @var{args}, are strings that specify command
line arguments for the program.
@ -331,7 +340,7 @@ input@point{}
@group
(call-process-region 1 6 "cat" nil t)
@result{} nil
@result{} 0
---------- Buffer: foo ----------
inputinput@point{}
@ -368,7 +377,7 @@ then returns the command's output as a string.
After an @dfn{asynchronous process} is created, Emacs and the subprocess
both continue running immediately. The process thereafter runs
in parallel with Emacs, and the two can communicate with each other
using the functions described in following sections. However,
using the functions described in the following sections. However,
communication is only partially asynchronous: Emacs sends data to the
process only when certain functions are called, and Emacs accepts data
from the process only when Emacs is waiting for input or for a time
@ -429,10 +438,10 @@ 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
arbitrary user-specified arguments 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}.
characters do @emph{not} have their special shell meanings. @xref{Shell
Arguments}.
@end defun
@defvar process-connection-type
@ -450,7 +459,7 @@ often better to use a pipe, because they are more efficient. In
addition, the total number of @sc{pty}s is limited on many systems and
it is good not to waste them.
The value @code{process-connection-type} is used when
The value of @code{process-connection-type} is used when
@code{start-process} is called. So you can specify how to communicate
with one subprocess by binding the variable around the call to
@code{start-process}.
@ -727,7 +736,7 @@ introduction.txt text.texi~
@end smallexample
@end defun
@deffn Command process-send-region process-name start end
@defun process-send-region process-name start end
This function sends the text in the region defined by @var{start} and
@var{end} as standard input to @var{process-name}, which is a process or
a process name. (If it is @code{nil}, the current buffer's process is
@ -736,7 +745,7 @@ used.)
An error is signaled unless both @var{start} and @var{end} are
integers or markers that indicate positions in the current buffer. (It
is unimportant which number is larger.)
@end deffn
@end defun
@defun process-send-eof &optional process-name
This function makes @var{process-name} see an end-of-file in its

285
lispref/searching.texi
View file

@ -34,9 +34,9 @@ portions of it.
These are the primitive functions for searching through the text in a
buffer. They are meant for use in programs, but you may call them
interactively. If you do so, they prompt for the search string;
@var{limit} and @var{noerror} are set to @code{nil}, and @var{repeat}
is set to 1.
interactively. If you do so, they prompt for the search string; the
arguments @var{limit} and @var{noerror} are @code{nil}, and @var{repeat}
is 1.
These search functions convert the search string to multibyte if the
buffer is multibyte; they convert the search string to unibyte if the
@ -167,6 +167,7 @@ regexps; the following section says how to search for them.
@menu
* Syntax of Regexps:: Rules for writing regular expressions.
* Regexp Functions:: Functions for operating on regular expressions.
* Regexp Example:: Illustrates regular expression syntax.
@end menu
@ -182,21 +183,33 @@ special characters will be defined in the future. Any other character
appearing in a regular expression is ordinary, unless a @samp{\}
precedes it.
For example, @samp{f} is not a special character, so it is ordinary, and
For example, @samp{f} is not a special character, so it is ordinary, and
therefore @samp{f} is a regular expression that matches the string
@samp{f} and no other string. (It does @emph{not} match the string
@samp{ff}.) Likewise, @samp{o} is a regular expression that matches
only @samp{o}.@refill
@samp{fg}, but it does match a @emph{part} of that string.) Likewise,
@samp{o} is a regular expression that matches only @samp{o}.@refill
Any two regular expressions @var{a} and @var{b} can be concatenated. The
Any two regular expressions @var{a} and @var{b} can be concatenated. The
result is a regular expression that matches a string if @var{a} matches
some amount of the beginning of that string and @var{b} matches the rest of
the string.@refill
As a simple example, we can concatenate the regular expressions @samp{f}
As a simple example, we can concatenate the regular expressions @samp{f}
and @samp{o} to get the regular expression @samp{fo}, which matches only
the string @samp{fo}. Still trivial. To do something more powerful, you
need to use one of the special characters. Here is a list of them:
need to use one of the special regular expression constructs.
@menu
* Regexp Special:: Special characters in regular expressions.
* Char Classes:: Character classes used in regular expressions.
* Regexp Backslash:: Backslash-sequences in regular expressions.
@end menu
@node Regexp Special
@subsubsection Special Characters in Regular Expressions
Here is a list of the characters that are special in a regular
expression.
@need 800
@table @asis
@ -266,23 +279,10 @@ matches @samp{cr}, @samp{car}, @samp{cdr}, @samp{caddaar}, etc.
You can also include character ranges in a character alternative, by
writing the starting and ending characters with a @samp{-} between them.
Thus, @samp{[a-z]} matches any lower-case @sc{ASCII} letter. Ranges may be
Thus, @samp{[a-z]} matches any lower-case @sc{ascii} letter. Ranges may be
intermixed freely with individual characters, as in @samp{[a-z$%.]},
which matches any lower case @sc{ASCII} letter or @samp{$}, @samp{%} or
which matches any lower case @sc{ascii} letter or @samp{$}, @samp{%} or
period.
You cannot always match all non-@sc{ASCII} characters with the regular
expression @samp{[\200-\377]}. This works when searching a unibyte
buffer or string (@pxref{Text Representations}), but not in a multibyte
buffer or string, because many non-@sc{ASCII} characters have codes
above octal 0377. However, the regular expression @samp{[^\000-\177]}
does match all non-@sc{ASCII} characters, in both multibyte and unibyte
representations, because only the @sc{ASCII} characters are excluded.
The beginning and end of a range must be in the same character set
(@pxref{Character Sets}). Thus, @samp{[a-\x8e0]} is invalid because
@samp{a} is in the @sc{ASCII} character set but the character 0x8e0
(@samp{a} with grave accent) is in the Emacs character set for Latin-1.
Note that the usual regexp special characters are not special inside a
character alternative. A completely different set of characters is
@ -297,6 +297,27 @@ matches both @samp{]} and @samp{-}.
To include @samp{^} in a character alternative, put it anywhere but at
the beginning.
The beginning and end of a range must be in the same character set
(@pxref{Character Sets}). Thus, @samp{[a-\x8e0]} is invalid because
@samp{a} is in the @sc{ascii} character set but the character 0x8e0
(@samp{a} with grave accent) is in the Emacs character set for Latin-1.
You cannot always match all non-@sc{ascii} characters with the regular
expression @samp{[\200-\377]}. This works when searching a unibyte
buffer or string (@pxref{Text Representations}), but not in a multibyte
buffer or string, because many non-@sc{ascii} characters have codes
above octal 0377. However, the regular expression @samp{[^\000-\177]}
does match all non-@sc{ascii} characters (see below regarding @samp{^}),
in both multibyte and unibyte representations, because only the
@sc{ascii} characters are excluded.
Starting in Emacs 21, a character alternative can also specify named
character classes (@pxref{Char Classes}). This is a POSIX feature whose
syntax is @samp{[:@var{class}:]}. Using a character class is equivalent
to mentioning each of the characters in that class; but the latter is
not feasible in practice, since some classes include thousands of
different characters.
@item @samp{[^ @dots{} ]}
@cindex @samp{^} in regexp
@samp{[^} begins a @dfn{complemented character alternative}, which matches any
@ -321,14 +342,21 @@ the beginning of a line.
When matching a string instead of a buffer, @samp{^} matches at the
beginning of the string or after a newline character @samp{\n}.
For historical compatibility reasons, @samp{^} can be used only at the
beginning of the regular expression, or after @samp{\(} or @samp{\|}.
@item @samp{$}
@cindex @samp{$} in regexp
@cindex end of line 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}.
For historical compatibility reasons, @samp{$} can be used only at the
end of the regular expression, or before @samp{\)} or @samp{\|}.
@item @samp{\}
@cindex @samp{\} in regexp
has two functions: it quotes the special characters (including
@ -354,11 +382,66 @@ ordinary since there is no preceding expression on which the @samp{*}
can act. It is poor practice to depend on this behavior; quote the
special character anyway, regardless of where it appears.@refill
For the most part, @samp{\} followed by any character matches only that
character. However, there are several exceptions: two-character
sequences starting with @samp{\} which have special meanings. (The
second character in such a sequence is always ordinary when used on its
own.) Here is a table of @samp{\} constructs.
@node Char Classes
@subsubsection Character Classes
@cindex character classes in regexp
Here is a table of the classes you can use in a character alternative,
in Emacs 21, and what they mean:
@table @samp
@item [:ascii:]
This matches any ASCII (unibyte) character.
@item [:alnum:]
This matches any letter or digit. (At present, for multibyte
characters, it matches anything that has word syntax.)
@item [:alpha:]
This matches any letter. (At present, for multibyte characters, it
matches anything that has word syntax.)
@item [:blank:]
This matches space and tab only.
@item [:cntrl:]
This matches any ASCII control character.
@item [:digit:]
This matches @samp{0} through @samp{9}. Thus, @samp{[-+[:digit:]]}
matches any digit, as well as @samp{+} and @samp{-}.
@item [:graph:]
This matches graphic characters---everything except ASCII control characters,
space, and DEL.
@item [:lower:]
This matches any lower-case letter, as determined by
the current case table (@pxref{Case Tables}).
@item [:nonascii:]
This matches any non-ASCII (multibyte) character.
@item [:print:]
This matches printing characters---everything except ASCII control
characters and DEL.
@item [:punct:]
This matches any punctuation character. (At present, for multibyte
characters, it matches anything that has non-word syntax.)
@item [:space:]
This matches any character that has whitespace syntax
(@pxref{Syntax Class Table}).
@item [:upper:]
This matches any upper-case letter, as determined by
the current case table (@pxref{Case Tables}).
@item [:word:]
This matches any character that has word syntax (@pxref{Syntax Class
Table}).
@item [:xdigit:]
This matches the hexadecimal digits: @samp{0} through @samp{9}, @samp{a}
through @samp{f} and @samp{A} through @samp{F}.
@end table
@node Regexp Backslash
@subsubsection Backslash Constructs in Regular Expressions
For the most part, @samp{\} followed by any character matches only
that character. However, there are several exceptions: certain
two-character sequences starting with @samp{\} that have special
meanings. (The character after the @samp{\} in such a sequence is
always ordinary when used on its own.) Here is a table of the special
@samp{\} constructs.
@table @samp
@item \|
@ -376,7 +459,9 @@ but no other string.@refill
surrounding @samp{\( @dots{} \)} grouping can limit the grouping power of
@samp{\|}.@refill
Full backtracking capability exists to handle multiple uses of @samp{\|}.
Full backtracking capability exists to handle multiple uses of
@samp{\|}, if you use the POSIX regular expression functions
(@pxref{POSIX Regexps}).
@item \( @dots{} \)
@cindex @samp{(} in regexp
@ -505,62 +590,6 @@ as @samp{[]]}), and so is a string that ends with a single @samp{\}. If
an invalid regular expression is passed to any of the search functions,
an @code{invalid-regexp} error is signaled.
@defun regexp-quote string
This function returns a regular expression string that matches exactly
@var{string} and nothing else. This allows you to request an exact
string match when calling a function that wants a regular expression.
@example
@group
(regexp-quote "^The cat$")
@result{} "\\^The cat\\$"
@end group
@end example
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 @var{string}, surrounded by
whitespace:
@example
@group
(re-search-forward
(concat "\\s-" (regexp-quote string) "\\s-"))
@end group
@end example
@end defun
@defun regexp-opt strings &optional paren
@tindex regexp-opt
This function returns an efficient regular expression that will match
any of the strings @var{strings}. This is useful when you need to make
matching or searching as fast as possible---for example, for Font Lock
mode.
If the optional argument @var{paren} is non-@code{nil}, then the
returned regular expression is always enclosed by at least one
parentheses-grouping construct.
This simplified definition of @code{regexp-opt} produces a
regular expression which is equivalent to the actual value
(but not as efficient):
@example
(defun regexp-opt (strings paren)
(let ((open-paren (if paren "\\(" ""))
(close-paren (if paren "\\)" "")))
(concat open-paren
(mapconcat 'regexp-quote strings "\\|")
close-paren)))
@end example
@end defun
@defun regexp-opt-depth regexp
@tindex regexp-opt-depth
This function returns the total number of grouping constructs
(parenthesized expressions) in @var{regexp}.
@end defun
@node Regexp Example
@comment node-name, next, previous, up
@subsection Complex Regexp Example
@ -624,6 +653,72 @@ Finally, the last part of the pattern matches any additional whitespace
beyond the minimum needed to end a sentence.
@end table
@node Regexp Functions
@subsection Regular Expression Functions
These functions operate on regular expressions.
@defun regexp-quote string
This function returns a regular expression whose only exact match is
@var{string}. Using this regular expression in @code{looking-at} will
succeed only if the next characters in the buffer are @var{string};
using it in a search function will succeed if the text being searched
contains @var{string}.
This allows you to request an exact string match or search when calling
a function that wants a regular expression.
@example
@group
(regexp-quote "^The cat$")
@result{} "\\^The cat\\$"
@end group
@end example
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 @var{string}, surrounded by
whitespace:
@example
@group
(re-search-forward
(concat "\\s-" (regexp-quote string) "\\s-"))
@end group
@end example
@end defun
@defun regexp-opt strings &optional paren
@tindex regexp-opt
This function returns an efficient regular expression that will match
any of the strings @var{strings}. This is useful when you need to make
matching or searching as fast as possible---for example, for Font Lock
mode.
If the optional argument @var{paren} is non-@code{nil}, then the
returned regular expression is always enclosed by at least one
parentheses-grouping construct.
This simplified definition of @code{regexp-opt} produces a
regular expression which is equivalent to the actual value
(but not as efficient):
@example
(defun regexp-opt (strings paren)
(let ((open-paren (if paren "\\(" ""))
(close-paren (if paren "\\)" "")))
(concat open-paren
(mapconcat 'regexp-quote strings "\\|")
close-paren)))
@end example
@end defun
@defun regexp-opt-depth regexp
@tindex regexp-opt-depth
This function returns the total number of grouping constructs
(parenthesized expressions) in @var{regexp}.
@end defun
@node Regexp Search
@section Regular Expression Searching
@cindex regular expression searching
@ -908,10 +1003,19 @@ The argument @var{replacements} specifies what to replace occurrences
with. If it is a string, that string is used. It can also be a list of
strings, to be used in cyclic order.
If @var{replacements} is a cons cell, @var{(@var{function}
. @var{data})}, this means to call @var{function} after each match to
get the replacement text. This function is called with two arguments:
@var{data}, and the number of replacements already made.
If @var{repeat-count} is non-@code{nil}, it should be an integer. Then
it specifies how many times to use each of the strings in the
@var{replacements} list before advancing cyclicly to the next one.
If @var{from-string} contains upper-case letters, then
@code{perform-replace} binds @code{case-fold-search} to @code{nil}, and
it uses the @code{replacements} without altering the case of them.
Normally, the keymap @code{query-replace-map} defines the possible user
responses for queries. The argument @var{map}, if non-@code{nil}, is a
keymap to use instead of @code{query-replace-map}.
@ -1009,7 +1113,7 @@ match data around it, to prevent it from being overwritten.
@end menu
@node Replacing Match
@subsection Replacing the Text That Matched
@subsection Replacing the Text that Matched
This function replaces the text matched by the last search with
@var{replacement}.
@ -1039,9 +1143,6 @@ 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
@ -1361,8 +1462,8 @@ preserve case. If the variable is @code{nil}, that means to use the
replacement text verbatim. A non-@code{nil} value means to convert the
case of the replacement text according to the text being replaced.
The function @code{replace-match} is where this variable actually has
its effect. @xref{Replacing Match}.
This variable is used by passing it as an argument to the function
@code{replace-match}. @xref{Replacing Match}.
@end defopt
@defopt case-fold-search

4
lispref/sequences.texi
View file

@ -3,7 +3,7 @@
@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/sequences
@node Sequences Arrays Vectors, Symbols, Lists, Top
@node Sequences Arrays Vectors, Hash Tables, Lists, Top
@chapter Sequences, Arrays, and Vectors
@cindex sequence
@ -312,7 +312,7 @@ first element is at index zero.
@end group
@group
(aref "abcdefg" 1)
@result{} 98 ; @r{@samp{b} is @sc{ASCII} code 98.}
@result{} 98 ; @r{@samp{b} is @sc{ascii} code 98.}
@end group
@end example

53
lispref/streams.texi
View file

@ -716,25 +716,25 @@ In the second expression, the local binding of
@tindex print-escape-nonascii
@defvar print-escape-nonascii
If this variable is non-@code{nil}, then unibyte non-@sc{ASCII}
If this variable is non-@code{nil}, then unibyte non-@sc{ascii}
characters in strings are unconditionally printed as backslash sequences
by the print functions @code{prin1} and @code{print} that print with
quoting.
Those functions also use backslash sequences for unibyte non-@sc{ASCII}
Those functions also use backslash sequences for unibyte non-@sc{ascii}
characters, regardless of the value of this variable, when the output
stream is a multibyte buffer or a marker pointing into one.
@end defvar
@tindex print-escape-multibyte
@defvar print-escape-multibyte
If this variable is non-@code{nil}, then multibyte non-@sc{ASCII}
If this variable is non-@code{nil}, then multibyte non-@sc{ascii}
characters in strings are unconditionally printed as backslash sequences
by the print functions @code{prin1} and @code{print} that print with
quoting.
Those functions also use backslash sequences for multibyte
non-@sc{ASCII} characters, regardless of the value of this variable,
non-@sc{ascii} characters, regardless of the value of this variable,
when the output stream is a unibyte buffer or a marker pointing into
one.
@end defvar
@ -766,3 +766,48 @@ parentheses and brackets when printed. Any list or vector at a depth
exceeding this limit is abbreviated with an ellipsis. A value of
@code{nil} (which is the default) means no limit.
@end defvar
These variables are used for detecting and reporting circular
and shared structure---but they are only defined in Emacs 21.
@tindex print-circle
@defvar print-circle
If non-@code{nil}, this variable enables detection of circular
and shared structure in printing.
@end defvar
@tindex print-gensym
@defvar print-gensym
If non-@code{nil}, this variable enables detection of uninterned symbols
(@pxref{Creating Symbols}) in printing. When this is enabled,
uninterned symbols print with the prefix @samp{#:}, which tells the Lisp
reader to produce an uninterned symbol.
@end defvar
@tindex print-continuous-numbering
@defvar print-continuous-numbering
To print several objects with shared structure in common, you should
bind @code{print-continuous-numbering} to @code{t} around them all.
That tells @code{print} not to reinitialize @code{print-number-table}
each time.
@end defvar
@tindex print-number-table
@defvar print-number-table
This variable holds the table used as the basis of outputting
@samp{#@var{n}=} and @samp{#@var{n}#} constructs for circular and shared
structure. When you want to print several objects with shared structure
in common, you should bind @code{print-number-table} to @code{nil}
around them all.
@end defvar
Here is an example of printing two objects with a common
set of shared substructure:
@example
(let ((print-circle t)
(print-continuous-numbering t)
print-number-table)
(print1 x)
(print1 y))
@end example

84
lispref/strings.texi
View file

@ -27,7 +27,7 @@ keyboard character events.
* Creating Strings:: Functions to allocate new strings.
* Modifying Strings:: Altering the contents of an existing string.
* Text Comparison:: Comparing characters or strings.
* String Conversion:: Converting characters or strings and vice versa.
* String Conversion:: Converting to and from characters and strings.
* Formatting Strings:: @code{format}: Emacs's analogue of @code{printf}.
* Case Conversion:: Case conversion functions.
* Case Tables:: Customizing case conversion.
@ -43,7 +43,7 @@ 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.)
C are terminated by a character with @sc{ascii} code 0.)
Since strings are arrays, and therefore sequences as well, you can
operate on them with the general array and sequence functions.
@ -51,25 +51,25 @@ operate on them with the general array and sequence functions.
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
There are two text representations for non-@sc{ascii} characters in
Emacs strings (and in buffers): unibyte and multibyte (@pxref{Text
Representations}). @sc{ASCII} characters always occupy one byte in a
string; in fact, when a string is all @sc{ASCII}, there is no real
Representations}). An @sc{ascii} character always occupies one byte in a
string; in fact, when a string is all @sc{ascii}, there is no real
difference between the unibyte and multibyte representations.
For most Lisp programming, you don't need to be concerned with these two
representations.
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 character
characters (which are 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
control characters. They do not distinguish case in @sc{ASCII} control
modifiers; they can hold @sc{ascii} control characters, but no other
control characters. They do not distinguish case in @sc{ascii} control
characters. If you want to store such characters in a sequence, such as
a key sequence, you must use a vector instead of a string.
@xref{Character Type}, for more information about representation of meta
@xref{Character Type}, for more information about the representation of meta
and other modifiers for keyboard input characters.
Strings are useful for holding regular expressions. You can also
@ -200,7 +200,7 @@ Functions}).
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.
@code{substring} also accepts a vector for the first argument.
For example:
@example
@ -250,8 +250,8 @@ When an argument is an integer (not a sequence of integers), it is
converted to a string of digits making up the decimal printed
representation of the integer. @strong{Don't use this feature; we plan
to eliminate it. If you already use this feature, change your programs
now!} The proper way to convert an integer to a decimal number in this
way is with @code{format} (@pxref{Formatting Strings}) or
now!} The proper way to convert an integer to its decimal printed form
is with @code{format} (@pxref{Formatting Strings}) or
@code{number-to-string} (@pxref{String Conversion}).
@example
@ -271,7 +271,7 @@ Lists}.
@defun split-string string separators
@tindex split-string
Split @var{string} into substrings in between matches for the regular
This function splits @var{string} into substrings at matches for the regular
expression @var{separators}. Each match for @var{separators} defines a
splitting point; the substrings between the splitting points are made
into a list, which is the value returned by @code{split-string}.
@ -367,7 +367,7 @@ The function @code{string=} ignores the text properties of the two
strings. When @code{equal} (@pxref{Equality Predicates}) compares two
strings, it uses @code{string=}.
If the strings 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
@ -379,9 +379,9 @@ Representations}.
@cindex lexical comparison
@defun string< string1 string2
@c (findex string< causes problems for permuted index!!)
This function compares two strings a character at a time. First it
scans both the strings at once to find the first pair of corresponding
characters that do not match. If the lesser character of those two is
This function compares two strings a character at a time. It
scans both the strings at the same time to find the first pair of corresponding
characters that do not match. If the lesser character of these two is
the character from @var{string1}, then @var{string1} is less, and this
function returns @code{t}. If the lesser character is the one from
@var{string2}, then @var{string1} is greater, and this function returns
@ -389,11 +389,11 @@ function returns @code{t}. If the lesser character is the one from
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
@sc{ascii} character set than their upper case counterparts; digits and
many punctuation characters have a lower numeric value than upper case
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}).
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
@group
@ -433,11 +433,12 @@ no characters is less than any other string.
@defun compare-strings string1 start1 end1 string2 start2 end2 &optional ignore-case
@tindex compare-strings
This function compares a specified part of @var{string1} with a
This function compares the specified part of @var{string1} with the
specified part of @var{string2}. The specified part of @var{string1}
runs from index @var{start1} up to index @var{end1} (default, the end of
the string). The specified part of @var{string2} runs from index
@var{start2} up to index @var{end2} (default, the end of the string).
runs from index @var{start1} up to index @var{end1} (@code{nil} means
the end of the string). The specified part of @var{string2} runs from
index @var{start2} up to index @var{end2} (@code{nil} means the end of
the string).
The strings are both converted to multibyte for the comparison
(@pxref{Text Representations}) so that a unibyte string can be equal to
@ -500,7 +501,7 @@ This function returns a new string containing one character,
@cindex string to character
This function returns the first character in @var{string}. If the
string is empty, the function returns 0. The value is also 0 when the
first character of @var{string} is the null character, @sc{ASCII} code
first character of @var{string} is the null character, @sc{ascii} code
0.
@example
@ -510,8 +511,10 @@ first character of @var{string} is the null character, @sc{ASCII} code
@result{} 120
(string-to-char "")
@result{} 0
@group
(string-to-char "\000")
@result{} 0
@end group
@end example
This function may be eliminated in the future if it does not seem useful
@ -523,7 +526,7 @@ enough to retain.
@cindex integer to decimal
This function returns a string consisting of the printed base-ten
representation of @var{number}, which may be an integer or a floating
point number. The value starts with a sign if the argument is
point number. The returned value starts with a minus sign if the argument is
negative.
@example
@ -553,8 +556,9 @@ more work and does not seem useful.
The parsing skips spaces and tabs at the beginning of @var{string}, then
reads as much of @var{string} as it can interpret as a number. (On some
systems it ignores other whitespace at the beginning, not just spaces
and tabs.) If the first character after the ignored whitespace is not a
digit or a plus or minus sign, this function returns 0.
and tabs.) If the first character after the ignored whitespace is
neither a digit, nor a plus or minus sign, nor the leading dot of a
floating point number, this function returns 0.
@example
(string-to-number "256")
@ -607,6 +611,10 @@ 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.
The characters in @var{string}, other than the format specifications,
are copied directly into the output; starting in Emacs 21, if they have
text properties, these are copied into the output also.
@end defun
@cindex @samp{%} in format
@ -646,6 +654,10 @@ made without quoting (that is, using @code{princ}, not
by their contents alone, with no @samp{"} characters, and symbols appear
without @samp{\} characters.
Starting in Emacs 21, if the object is a string, its text properties are
copied into the output. The text properties of the @samp{%s} itself
are also copied, but those of the object take priority.
If there is no corresponding object, the empty string is used.
@item %S
@ -774,15 +786,15 @@ not truncated. In the third case, the padding is on the right.
The character case functions change the case of single characters or
of the contents of strings. The functions normally convert only
alphabetic characters (the letters @samp{A} through @samp{Z} and
@samp{a} through @samp{z}, as well as non-ASCII letters); other
characters are not altered. (You can specify a different case
conversion mapping by specifying a case table---@pxref{Case Tables}.)
@samp{a} through @samp{z}, as well as non-@sc{ascii} letters); other
characters are not altered. You can specify a different case
conversion mapping by specifying a case table (@pxref{Case Tables}).
These functions do not modify the strings that are passed to them as
arguments.
The examples below use the characters @samp{X} and @samp{x} which have
@sc{ASCII} codes 88 and 120 respectively.
@sc{ascii} codes 88 and 120 respectively.
@defun downcase string-or-char
This function converts a character or a string to lower case.
@ -814,7 +826,7 @@ lower case is converted to upper case.
When the argument to @code{upcase} is a character, @code{upcase}
returns the corresponding upper case character. This value is an integer.
If the original character is upper case, or is not a letter, then the
value equals the original character.
value returned equals the original character.
@example
(upcase "The cat in the hat")
@ -921,7 +933,7 @@ of them, or @samp{A} for both of them).
The extra table @var{equivalences} is a map that cyclicly permutes
each equivalence class (of characters with the same canonical
equivalent). (For ordinary @sc{ASCII}, this would map @samp{a} into
equivalent). (For ordinary @sc{ascii}, this would map @samp{a} into
@samp{A} and @samp{A} into @samp{a}, and likewise for each set of
equivalent characters.)
@ -958,7 +970,7 @@ This sets the current buffer's case table to @var{table}.
@end defun
The following three functions are convenient subroutines for packages
that define non-@sc{ASCII} character sets. They modify the specified
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}. Normally you would use these functions to change
the standard case table.

19
lispref/symbols.texi
View file

@ -3,7 +3,7 @@
@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/symbols
@node Symbols, Evaluation, Sequences Arrays Vectors, Top
@node Symbols, Evaluation, Hash Tables, Top
@chapter Symbols
@cindex symbol
@ -57,7 +57,7 @@ The @dfn{function cell} holds the function definition of the symbol.
When a symbol is used as a function, its function definition is used in
its place. This cell is also used to make a symbol stand for a keymap
or a keyboard macro, for editor command execution. Because each symbol
has separate value and function cells, variables and function names do
has separate value and function cells, variables names and function names do
not conflict. See @code{symbol-function} in @ref{Function Cells}.
@item Property list
@ -194,7 +194,9 @@ book cover to cover when looking up Jan Jones, you start with the J's
and go from there. That is a simple version of hashing. Each element
of the obarray is a @dfn{bucket} which holds all the symbols with a
given hash code; to look for a given name, it is sufficient to look
through all the symbols in the bucket for that name's hash code.
through all the symbols in the bucket for that name's hash code. (The
same idea is used for general Emacs hash tables, but they are a
different data type; see @ref{Hash Tables}.)
@cindex interning
If a symbol with the desired name is found, the reader uses that
@ -208,6 +210,11 @@ particular name. Other like-named symbols may exist, but not in the
same obarray. Thus, the reader gets the same symbols for the same
names, as long as you keep reading with the same obarray.
Interning usually happens automatically in the reader, but sometimes
other programs need to do it. For example, after the @kbd{M-x} command
obtains the command name as a string using the minibuffer, it then
interns the string, to get the interned symbol with that name.
@cindex symbol equality
@cindex uninterned symbol
No obarray contains all symbols; in fact, some symbols are not in any
@ -216,6 +223,10 @@ symbol has the same four cells as other symbols; however, the only way
to gain access to it is by finding it in some other object or as the
value of a variable.
Creating an uninterned symbol is useful in generating Lisp code,
because an uninterned symbol used as a variable in the code you generate
cannot clash with any variables used in other Lisp programs.
In Emacs Lisp, an obarray is actually a vector. Each element of the
vector is a bucket; its value is either an interned symbol whose name
hashes to that bucket, or 0 if the bucket is empty. Each interned
@ -224,7 +235,7 @@ in the bucket. Because these links are invisible, there is no way to
find all the symbols in an obarray except using @code{mapatoms} (below).
The order of symbols in a bucket is not significant.
In an empty obarray, every element is 0, and you can create an obarray
In an empty obarray, every element is 0, so you can create an obarray
with @code{(make-vector @var{length} 0)}. @strong{This is the only
valid way to create an obarray.} Prime numbers as lengths tend
to result in good hashing; lengths one less than a power of two are also

23
lispref/syntax.texi
View file

@ -71,7 +71,7 @@ A syntax table can inherit the data for some characters from the
standard syntax table, while specifying other characters itself. The
``inherit'' syntax class means ``inherit this character's syntax from
the standard syntax table.'' Just changing the standard syntax for a
characters affects all syntax tables which inherit from it.
character affects all syntax tables that inherit from it.
@defun syntax-table-p object
This function returns @code{t} if @var{object} is a syntax table.
@ -92,9 +92,11 @@ 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
designator character is one that is frequently in that class; however,
designator character is one that is often assigned that class; however,
its meaning as a designator is unvarying and independent of what syntax
that character currently has.
that character currently has. Thus, @samp{\} as a designator character
always gives ``escape character'' syntax, regardless of what syntax
@samp{\} currently has.
@cindex syntax descriptor
A syntax descriptor is a Lisp string that specifies a syntax class, a
@ -106,7 +108,7 @@ character or flags are needed, one character is sufficient.
For example, the syntax descriptor for the character @samp{*} in C
mode is @samp{@w{. 23}} (i.e., punctuation, matching character slot
unused, second character of a comment-starter, first character of an
unused, second character of a comment-starter, first character of a
comment-ender), and the entry for @samp{/} is @samp{@w{. 14}} (i.e.,
punctuation, matching character slot unused, first character of a
comment-starter, second character of a comment-ender).
@ -542,6 +544,10 @@ This function moves point forward across characters having syntax classes
mentioned in @var{syntaxes}. It stops when it encounters the end of
the buffer, or position @var{limit} (if specified), or a character it is
not supposed to skip.
If @var{syntaxes} starts with @samp{^}, then the function skips
characters whose syntax is @emph{not} in @var{syntaxes}.
The return value is the distance traveled, which is a nonnegative
integer.
@end defun
@ -549,8 +555,11 @@ integer.
@defun skip-syntax-backward syntaxes &optional limit
This function moves point backward across characters whose syntax
classes are mentioned in @var{syntaxes}. It stops when it encounters
the beginning of the buffer, or position @var{limit} (if specified), or a
character it is not supposed to skip.
the beginning of the buffer, or position @var{limit} (if specified), or
a character it is not supposed to skip.
If @var{syntaxes} starts with @samp{^}, then the function skips
characters whose syntax is @emph{not} in @var{syntaxes}.
The return value indicates the distance traveled. It is an integer that
is zero or less.
@ -856,7 +865,7 @@ 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
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}.

75
lispref/text.texi
View file

@ -220,6 +220,9 @@ This is the contents of buffer foo
"
@end group
@end example
When this function is used in the minibuffer, the value does not include
the prompt.
@end defun
@defun thing-at-point thing
@ -275,7 +278,7 @@ and @samp{rara!}. The value is 2 because the first substring is greater
at the second character.
@example
(compare-buffer-substring nil 6 11 nil 16 21)
(compare-buffer-substrings nil 6 11 nil 16 21)
@result{} 2
@end example
@end defun
@ -482,6 +485,8 @@ empty. If the buffer is read-only, it signals a @code{buffer-read-only}
error. Otherwise, it deletes the text without asking for any
confirmation. It returns @code{nil}.
In the minibuffer, @code{erase-buffer} does not delete the prompt.
Normally, deleting a large amount of text from a buffer inhibits further
auto-saving of that buffer ``because it has shrunk''. However,
@code{erase-buffer} does not do this, the idea being that the future
@ -1790,8 +1795,8 @@ converts the tab into spaces so that it can move precisely to column
@var{force}, since there is no way to split them.
The argument @var{force} also has an effect if the line isn't long
enough to reach column @var{column}; in that case, it says to add
whitespace at the end of the line to reach that column.
enough to reach column @var{column}; if it is @code{t}, that means to
add whitespace at the end of the line to reach that column.
If @var{column} is not an integer, an error is signaled.
@ -2540,14 +2545,31 @@ of the symbol serve as defaults for the properties of the character.
@cindex face codes of text
@kindex face @r{(text property)}
You can use the property @code{face} to control the font and color of
text. Its value is a face name or a list of face names. @xref{Faces},
for more information.
text. @xref{Faces}, for more information.
If the property value is a list, elements may also have the form
@code{(foreground-color . @var{color-name})} or @code{(background-color
. @var{color-name})}. These elements specify just the foreground color
or just the background color; therefore, there is no need to create a
face for each color that you want to use.
In the simplest case, the value is a face name. It can also be a list;
then each element can be any of these possibilities;
@itemize @bullet
@item
A face name (a symbol or string).
@item
Starting in Emacs 21, a property list of face attributes. This has the
form (@var{keyword} @var{value} @dots{}), where each @var{keyword} is a
face attribute name and @var{value} is a meaningful value for that
attribute. With this feature, you do not need to create a face each
time you want to specify a particular attribute for certain text.
@xref{Face Attributes}.
@item
A cons cell of the form @code{(foreground-color . @var{color-name})} or
@code{(background-color . @var{color-name})}. These elements specify
just the foreground color or just the background color.
@code{(foreground-color . @var{color-name})} is equivalent to
@code{(:foreground @var{color-name})}, and likewise for the background.
@end itemize
@xref{Font Lock Mode}, for information on how to update @code{face}
properties automatically based on the contents of the text.
@ -2559,6 +2581,26 @@ mouse is on or near the character. For this purpose, ``near'' means
that all text between the character and where the mouse is have the same
@code{mouse-face} property value.
@item fontified
@kindex fontified @r{(text property)}
This property, if non-@code{nil}, says that text in the buffer has
had faces assigned automatically by a feature such as Font-Lock mode.
@xref{Auto Faces}.
@item display
@kindex display @r{(text property)}
This property activates various features that change the
way text is displayed. For example, it can make text appear taller
or shorter, higher or lower, wider or narror, or replaced with an image.
@xref{Display Property}.
@item help-echo
@kindex help-echo @r{(text property)}
If text has a string as its @code{help-echo} property, then when you
move the mouse onto that text, Emacs displays that string in the echo
area, or in the tooltip window. This feature is used in the mode line.
It is available starting in Emacs 21.
@item local-map
@cindex keymap of character
@kindex local-map @r{(text property)}
@ -3231,7 +3273,7 @@ all markers unrelocated.
@cindex base 64 encoding
Base 64 code is used in email to encode a sequence of 8-bit bytes as a
longer sequence of @sc{ASCII} graphic characters. This section
longer sequence of @sc{ascii} graphic characters. This section
describes the functions for converting to and from this code.
@defun base64-encode-region beg end &optional no-line-break
@ -3377,3 +3419,14 @@ to call. Here is an example:
This variable is a normal hook that is run whenever a buffer is changed
that was previously in the unmodified state.
@end defvar
@defvar inhibit-modification-hooks
@tindex inhibit-modification-hooks
If this variable is non-@code{nil}, all of the change hooks are
disabled; none of them run. This affects all the hook variables
described above in this section, as well as the hooks attached to
certain special text properties (@pxref{Special Properties}) and overlay
properties (@pxref{Overlay Properties}).
This variable is available starting in Emacs 21.
@end defvar

66
lispref/tips.texi
View file

@ -14,6 +14,12 @@ it gives advice on making effective use of the features described in the
previous chapters, and describes conventions Emacs Lisp programmers
should follow.
You can automatically check some of the conventions described below by
running the command @kbd{M-x checkdoc RET} when visiting a Lisp file.
It cannot check all of the conventions, and not all the warnings it
gives necessarily correspond to problems, but it is worth examining them
all.
@menu
* Coding Conventions:: Conventions for clean and robust programs.
* Compilation Tips:: Making compiled code run fast.
@ -287,6 +293,17 @@ coherent if all libraries use the same conventions.
Try to avoid compiler warnings about undefined free variables, by adding
@code{defvar} definitions for these variables.
Sometimes adding a @code{require} for another package is useful to avoid
compilation warnings for variables and functions defined in that
package. If you do this, often it is better if the @cpde{require} acts
only at compile time. Here's how to do that:
@example
(eval-when-compile
(require 'foo)
(defvar bar-baz))
@end example
If you bind a variable in one function, and use it or set it in another
function, the compiler warns about the latter function unless the
variable has a definition. But often these variables have short names,
@ -421,12 +438,12 @@ should be made up of complete sentences also, but they may be filled if
that looks good.
@item
For consistency, phrase the verb in the first sentence of a
function's documentation string as an infinitive with ``to'' omitted. For
instance, use ``Return the cons of A and B.'' in preference to ``Returns
the cons of A and B@.'' Usually it looks good to do likewise for the
rest of the first paragraph. Subsequent paragraphs usually look better
if they have proper subjects.
For consistency, phrase the verb in the first sentence of a function's
documentation string as an imperative--for instance, use ``Return the
cons of A and B.'' in preference to ``Returns the cons of A and B@.''
Usually it looks good to do likewise for the rest of the first
paragraph. Subsequent paragraphs usually look better if each sentence
has a proper subject.
@item
Write documentation strings in the active voice, not the passive, and in
@ -485,9 +502,15 @@ a name for that value. Thus, the documentation string of the function
@code{/} refers to its second argument as @samp{DIVISOR}, because the
actual argument name is @code{divisor}.
Also use all caps for meta-syntactic variables, such as when you show
Also use all caps for metasyntactic variables, such as when you show
the decomposition of a list or vector into subunits, some of which may
vary.
vary. @samp{KEY} and @samp{VALUE} in the following example
illustrate this practice:
@example
The argument TABLE should be an alist whose elements
have the form (KEY . VALUE). Here, KEY is ...
@end example
@item
@iftex
@ -537,6 +560,14 @@ that satisfy the criterion.
does not make a hyperlink to the documentation, irrelevant here, of the
function @code{list}.
To make a hyperlink to Info documentation, write the name of the Info
node in single quotes, preceded by @samp{info node} or @samp{Info
node}. The Info file name defaults to @samp{emacs}. For example,
@smallexample
See Info node `Font Lock' and Info node `(elisp)Font Lock Basics'.
@end smallexample
@item
Don't write key sequences directly in documentation strings. Instead,
use the @samp{\\[@dots{}]} construct to stand for them. For example,
@ -659,7 +690,21 @@ Manipulating Comments, emacs, The GNU Emacs Manual}.
Emacs has conventions for using special comments in Lisp libraries
to divide them into sections and give information such as who wrote
them. This section explains these conventions. First, an example:
them. This section explains these conventions.
We'll start with an example, a package that is included in the Emacs
distribution.
Parts of this example reflect its status as part of Emacs; for
example, the copyright notice lists the Free Software Foundation as the
copyright holder, and the copying permission says the file is part of
Emacs. When you write a package and post it, the copyright holder would
be you (unless your employer claims to own it instead), and you should
get the suggested copying permission from the end of the GNU General
Public License itself. Don't say your file is part of Emacs
if we haven't installed it in Emacs yet!
With that warning out of the way, on to the example:
@smallexample
@group
@ -773,7 +818,8 @@ This begins change log information stored in the library file (if you
store the change history there). For most of the Lisp
files distributed with Emacs, the change history is kept in the file
@file{ChangeLog} and not in the source file at all; these files do
not have a @samp{;;; Change Log:} line.
not have a @samp{;;; Change Log:} line. @samp{History} is an
alternative to @samp{Change Log}.
@item ;;; Code:
This begins the actual code of the program.

33
lispref/variables.texi
View file

@ -94,7 +94,7 @@ x
@end example
@node Constant Variables
@section Variables That Never Change
@section Variables that Never Change
@vindex nil
@vindex t
@kindex setting-constant
@ -104,8 +104,8 @@ 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 a symbol to
itself.
starts with @samp{:} (if it is interned in the standard obarray), except
that you are allowed to set such a symbol to itself.
@example
@group
@ -563,8 +563,9 @@ then the variable is a user option.
If a user option variable has a @code{variable-interactive} property,
the @code{set-variable} command uses that value to control reading the
new value for the variable. The property's value is used as if it were
to @code{interactive} (@pxref{Using Interactive}). However, this feature
is largely obsoleted by @code{defcustom} (@pxref{Customization}).
specified in @code{interactive} (@pxref{Using Interactive}). However,
this feature is largely obsoleted by @code{defcustom}
(@pxref{Customization}).
@strong{Warning:} If the @code{defconst} and @code{defvar} special
forms are used while the variable has a local binding, they set the
@ -606,8 +607,7 @@ variable. Here's a safe way to avoid that:
@example
(defvar my-mode-map nil
@var{docstring})
(if my-mode-map
nil
(unless my-mode-map
(let ((map (make-sparse-keymap)))
(define-key my-mode-map "\C-c\C-a" 'my-command)
@dots{}
@ -624,8 +624,7 @@ each form, if you do want to reinitialize the variable.
@example
(defvar my-mode-map nil
@var{docstring})
(if my-mode-map
nil
(unless my-mode-map
(setq my-mode-map (make-sparse-keymap))
(define-key my-mode-map "\C-c\C-a" 'my-command)
@dots{})
@ -854,10 +853,10 @@ the others.
@cindex dynamic scoping
Local bindings in Emacs Lisp have @dfn{indefinite scope} and
@dfn{dynamic extent}. @dfn{Scope} refers to @emph{where} textually in
the source code the binding can be accessed. Indefinite scope means
the source code the binding can be accessed. ``Indefinite scope'' means
that any part of the program can potentially access the variable
binding. @dfn{Extent} refers to @emph{when}, as the program is
executing, the binding exists. Dynamic extent means that the binding
executing, the binding exists. ``Dynamic extent'' means that the binding
lasts as long as the activation of the construct that established it.
The combination of dynamic extent and indefinite scope is called
@ -902,9 +901,9 @@ definitions:
In a lexically scoped language, the binding of @code{x} in
@code{binder} would never be accessible in @code{user}, because
@code{user} is not textually contained within the function
@code{binder}. However, in dynamically scoped Emacs Lisp, @code{user}
@code{binder}. However, in dynamically-scoped Emacs Lisp, @code{user}
may or may not refer to the binding of @code{x} established in
@code{binder}, depending on circumstances:
@code{binder}, depending on the circumstances:
@itemize @bullet
@item
@ -1065,9 +1064,9 @@ use short names like @code{x}.
@cindex buffer-local variables
Global and local variable bindings are found in most programming
languages in one form or another. Emacs also supports additional,
languages in one form or another. Emacs, however, 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
apply only in one buffer, and @dfn{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.
@ -1100,7 +1099,7 @@ this is the global binding.
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. (This includes all
newly created buffers.) If you set the variable in a buffer that does
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
@ -1239,7 +1238,7 @@ If the variable is terminal-local, this function signals an error. Such
variables cannot have buffer-local bindings as well. @xref{Multiple
Displays}.
@strong{Note:} do not use @code{make-local-variable} for a hook
@strong{Note:} Do not use @code{make-local-variable} for a hook
variable. Instead, use @code{make-local-hook}. @xref{Hooks}.
@end deffn

348
lispref/windows.texi
View file

@ -23,8 +23,9 @@ displayed in windows.
* Window Point:: Each window has its own location of point.
* Window Start:: The display-start position controls which text
is on-screen in the window.
* Vertical Scrolling:: Moving text up and down in the window.
* Horizontal Scrolling:: Moving text sideways on the window.
* Textual Scrolling:: Moving text up and down through the window.
* Vertical Scrolling:: Moving the contents up and down on the window.
* Horizontal Scrolling:: Moving the contents sideways on the window.
* Size of Window:: Accessing the size of a window.
* Resizing Windows:: Changing the size of a window.
* Coordinates and Windows:: Converting coordinates to windows.
@ -251,40 +252,32 @@ characters. The display table can specify alternative border
characters; see @ref{Display Tables}.
@end deffn
@deffn Command split-window-vertically size
@deffn Command split-window-vertically &optional size
This function splits the selected window into two windows, one above the
other, leaving the upper of the two windows selected, with @var{size}
lines. (If @var{size} is negative, then the lower of the two windows
gets @minus{} @var{size} lines and the upper window gets the rest, but
the upper window is still the one selected.)
This function is simply an interface to @code{split-window}.
Here is the complete function definition for it:
@smallexample
@group
(defun split-window-vertically (&optional arg)
"Split current window into two windows, @dots{}"
(interactive "P")
(split-window nil (and arg (prefix-numeric-value arg))))
@end group
@end smallexample
@end deffn
@deffn Command split-window-horizontally size
This function splits the selected window into two windows
side-by-side, leaving the selected window with @var{size} columns.
This function is simply an interface to @code{split-window}. Here is
the complete definition for @code{split-window-horizontally} (except for
part of the documentation string):
This function is basically an interface to @code{split-window}.
You could define a simplified version of the function like this:
@smallexample
@group
(defun split-window-horizontally (&optional arg)
"Split selected window into two windows, side by side..."
(interactive "P")
(split-window nil (and arg (prefix-numeric-value arg)) t))
@endgroup
@group
(let ((size (and arg (prefix-numeric-value arg))))
(and size (< size 0)
(setq size (+ (window-width) size)))
(split-window nil size t)))
@end group
@end smallexample
@end deffn
@ -565,11 +558,15 @@ ordering of windows. The other arguments specify which windows to
include in the cycle, as in @code{next-window}.
@end defun
@deffn Command other-window count
@deffn Command other-window count &optional all-frames
This function selects the @var{count}th following window in the cyclic
order. If count is negative, then it moves back @minus{}@var{count}
windows in the cycle, rather than forward. It returns @code{nil}.
The argument @var{all-frames} has the same meaning is as in
@code{next-window}, but the @var{minibuf} argument of @code{next-window}
is always effectively @code{nil}.
In an interactive call, @var{count} is the numeric prefix argument.
@end deffn
@ -895,11 +892,11 @@ variable is a function that creates a frame using parameters from
@code{pop-up-frame-alist}.
@end defvar
@defvar pop-up-frame-alist
@defopt pop-up-frame-alist
This variable holds an alist specifying frame parameters used when
@code{display-buffer} makes a new frame. @xref{Frame Parameters}, for
more information about frame parameters.
@end defvar
@end defopt
@defopt special-display-buffer-names
A list of buffer names for buffers that should be displayed specially.
@ -938,16 +935,24 @@ The default value of this variable is
@code{special-display-popup-frame}.
@end defvar
@defun special-display-popup-frame buffer
@defun special-display-popup-frame buffer &rest args
This function makes @var{buffer} visible in a frame of its own. If
@var{buffer} is already displayed in a window in some frame, it makes
the frame visible and raises it, to use that window. Otherwise, it
creates a frame that will be dedicated to @var{buffer}.
This function uses an existing window displaying @var{buffer} whether or
not it is in a frame of its own; but if you set up the above variables
in your init file, before @var{buffer} was created, then presumably the
window was previously made by this function.
If @var{args} is an alist, it specifies frame parameters for the new
frame.
If @var{args} is a list whose @sc{car} is a symbol, then @code{(car
@var{args})} is called as a function to actually create and set up the
frame; it is called with @var{buffer} as first argument, and @code{(cdr
@var{args})} as additional arguments.
This function always uses an existing window displaying @var{buffer},
whether or not it is in a frame of its own; but if you set up the above
variables in your init file, before @var{buffer} was created, then
presumably the window was previously made by this function.
@end defun
@defopt special-display-frame-alist
@ -1035,10 +1040,11 @@ point and the buffer's point always move together; they remain equal.
when the user switches to another buffer, the cursor jumps to the
position of point in that buffer.
@defun window-point window
@defun window-point &optional window
This function returns the current position of point in @var{window}.
For a nonselected window, this is the value point would have (in that
window's buffer) if that window were selected.
window's buffer) if that window were selected. If @var{window} is
@code{nil}, the selected window is used.
When @var{window} is the selected window and its buffer is also the
current buffer, the value returned is the same as point in that buffer.
@ -1081,10 +1087,11 @@ display-start position is set to a display-start position recently used
for the same buffer, or 1 if the buffer doesn't have any.
Redisplay updates the window-start position (if you have not specified
it explicitly since the previous redisplay) so that point appears on the
screen. Nothing except redisplay automatically changes the window-start
position; if you move point, do not expect the window-start position to
change in response until after the next redisplay.
it explicitly since the previous redisplay)---for example, to make sure
point appears on the screen. Nothing except redisplay automatically
changes the window-start position; if you move point, do not expect the
window-start position to change in response until after the next
redisplay.
For a realistic example of using @code{window-start}, see the
description of @code{count-lines} in @ref{Text Lines}.
@ -1188,18 +1195,22 @@ argument @var{position} defaults to the current position of point;
The @code{pos-visible-in-window-p} function considers only vertical
scrolling. If @var{position} is out of view only because @var{window}
has been scrolled horizontally, @code{pos-visible-in-window-p} returns
@code{t}. @xref{Horizontal Scrolling}.
@code{t} anyway. @xref{Horizontal Scrolling}.
@end defun
@node Vertical Scrolling
@section Vertical Scrolling
@cindex vertical scrolling
@cindex scrolling vertically
@node Textual Scrolling
@section Textual Scrolling
@cindex textual scrolling
@cindex scrolling textually
Vertical scrolling means moving the text up or down in a window. It
works by changing the value of the window's display-start location. It
may also change the value of @code{window-point} to keep it on the
screen.
@dfn{Textual scrolling} means moving the text up or down though a
window. It works by changing the value of the window's display-start
location. It may also change the value of @code{window-point} to keep
point on the screen.
Textual scrolling was formerly called ``vertical scrolling,'' but we
changed its name to distinguish it from the new vertical fractional
scrolling feature (@pxref{Vertical Scrolling}).
In the commands @code{scroll-up} and @code{scroll-down}, the directions
``up'' and ``down'' refer to the motion of the text in the buffer at which
@ -1218,9 +1229,10 @@ position of a window on the terminal does not move, and short scrolling
commands clearly move the text up or down on the screen. We have chosen
names that fit the user's point of view.
The scrolling functions (aside from @code{scroll-other-window}) have
unpredictable results if the current buffer is different from the buffer
that is displayed in the selected window. @xref{Current Buffer}.
The textual scrolling functions (aside from
@code{scroll-other-window}) have unpredictable results if the current
buffer is different from the buffer that is displayed in the selected
window. @xref{Current Buffer}.
@deffn Command scroll-up &optional count
This function scrolls the text in the selected window upward
@ -1251,10 +1263,14 @@ This function scrolls the text in another window upward @var{count}
lines. Negative values of @var{count}, or @code{nil}, are handled
as in @code{scroll-up}.
You can specify a buffer to scroll with the variable
@code{other-window-scroll-buffer}. When the selected window is the
minibuffer, the next window is normally the one at the top left corner.
You can specify a different window to scroll with the variable
You can specify which buffer to scroll by setting the variable
@code{other-window-scroll-buffer} to a buffer. If that buffer isn't
already displayed, @code{scroll-other-window} displays it in some
window.
When the selected window is the minibuffer, the next window is normally
the one at the top left corner. You can specify a different window to
scroll, when the minibuffer is selected, by setting the variable
@code{minibuffer-scroll-window}. This variable has no effect when any
other window is selected. @xref{Minibuffer Misc}.
@ -1353,43 +1369,122 @@ Replaces three keystroke sequence C-u 0 C-l."
@end example
@end deffn
@node Vertical Scrolling
@section Vertical Fractional Scrolling
@cindex Vertical Fractional Scrolling
@dfn{Vertical fractional scrolling} means shifting the image in the
window up or down by a specified multiple or fraction of a line.
Starting in Emacs 21, each window has a @dfn{vertical scroll position},
which is a number, never less than zero. It specifies how far to raise
the contents of the window. Raising the window contents generally makes
all or part of some lines disappear off the top, and all or part of some
other lines appear at the bottom. The usual value is zero.
The vertical scroll position is measured in units of the normal line
height, which is the height of the default font. Thus, if the value is
.5, that means the window contents are scrolled up half the normal line
height. If it is 3.3, that means the window contents are scrolled up
somewhat over three times the normal line height.
What fraction of a line the vertical scrolling covers, or how many
lines, depends on what the lines contain. A value of .5 could scroll a
line whose height is very short off the screen, while a value of 3.3
could scroll just part of the way through a tall line or an image.
@defun window-vscroll &optional window
This function returns the current vertical scroll position of
@var{window}, If @var{window} is @code{nil}, the selected window is
used.
@example
@group
(window-vscroll)
@result{} 0
@end group
@end example
@end defun
@defun set-window-vscroll window lines
This function sets @var{window}'s vertical scroll position to
@var{lines}. The argument @var{lines} should be zero or positive; if
not, it is taken as zero.
The actual vertical scroll position must always correspond
to an integral number of pixels, so the value you specify
is rounded accordingly.
The return value is the result of this rounding.
@example
@group
(set-window-vscroll (selected-window) 1.2)
@result{} 1.13
@end group
@end example
@end defun
@node Horizontal Scrolling
@section Horizontal Scrolling
@cindex horizontal scrolling
Because we read English from left to right in the ``inner loop'', and
from top to bottom in the ``outer loop'', horizontal scrolling is not
like vertical scrolling. Vertical scrolling involves selection of a
contiguous portion of text to display, but horizontal scrolling causes
part of each line to go off screen. The amount of horizontal scrolling
is therefore specified as a number of columns rather than as a position
in the buffer. It has nothing to do with the display-start position
returned by @code{window-start}.
@dfn{Horizontal scrolling} means shifting the image in the window left
or right by a specified multiple of the normal character width. Each
window has a @dfn{vertical scroll position}, which is a number, never
less than zero. It specifies how far to shift the contents left.
Shifting the window contents left generally makes all or part of some
characters disappear off the left, and all or part of some other
characters appear at the right. The usual value is zero.
The horizontal scroll position is measured in units of the normal
character width, which is the width of space in the default font. Thus,
if the value is 5, that means the window contents are scrolled left by 5
times the the normal character width. How many characters actually
disappear off to the left depends on their width, and could vary from
line to line.
Because we read from side to side in the ``inner loop'', and from top
to bottom in the ``outer loop'', the effect of horizontal scrolling is
not like that of textual or vertical scrolling. Textual scrolling
involves selection of a portion of text to display, and vertical
scrolling moves the window contents contiguously; but horizontal
scrolling causes part of @emph{each line} to go off screen.
Usually, no horizontal scrolling is in effect; then the leftmost
column is at the left edge of the window. In this state, scrolling to
the right is meaningless, since there is no data to the left of the
screen to be revealed by it; so this is not allowed. Scrolling to the
left is allowed; it scrolls the first columns of text off the edge of
the window and can reveal additional columns on the right that were
truncated before. Once a window has a nonzero amount of leftward
horizontal scrolling, you can scroll it back to the right, but only so
far as to reduce the net horizontal scroll to zero. There is no limit
to how far left you can scroll, but eventually all the text will
disappear off the left edge.
the right is meaningless, since there is no data to the left of the edge
to be revealed by it; so this is not allowed. Scrolling to the left is
allowed; it scrolls the first columns of text off the edge of the window
and can reveal additional columns on the right that were truncated
before. Once a window has a nonzero amount of leftward horizontal
scrolling, you can scroll it back to the right, but only so far as to
reduce the net horizontal scroll to zero. There is no limit to how far
left you can scroll, but eventually all the text will disappear off the
left edge.
@deffn Command scroll-left count
In Emacs 21, redisplay automatically alters the horizontal scrolling
of a window as necessary to ensure that point is always visible.
However, you can still set the horizontal scrolling value explicitly.
The value you specify will be used, provided it leaves point visible.
@deffn Command scroll-left &optional count
This function scrolls the selected window @var{count} columns to the
left (or to the right if @var{count} is negative). The return value is
the total amount of leftward horizontal scrolling in effect after the
change---just like the value returned by @code{window-hscroll} (below).
left (or to the right if @var{count} is negative). The default
for @var{count} is the window width, minus 2.
The return value is the total amount of leftward horizontal scrolling in
effect after the change---just like the value returned by
@code{window-hscroll} (below).
@end deffn
@deffn Command scroll-right count
@deffn Command scroll-right &optional count
This function scrolls the selected window @var{count} columns to the
right (or to the left if @var{count} is negative). The return value is
the total amount of leftward horizontal scrolling in effect after the
change---just like the value returned by @code{window-hscroll} (below).
right (or to the left if @var{count} is negative). The default
for @var{count} is the window width, minus 2.
The return value is the total amount of leftward horizontal scrolling in
effect after the change---just like the value returned by
@code{window-hscroll} (below).
Once you scroll a window as far right as it can go, back to its normal
position where the total leftward scrolling is zero, attempts to scroll
@ -1426,6 +1521,7 @@ If @var{window} is @code{nil}, the selected window is used.
This function sets the number of columns from the left margin that
@var{window} is scrolled from the value of @var{columns}. The argument
@var{columns} should be zero or positive; if not, it is taken as zero.
Fractional values of @var{columns} are not supported at present.
The value returned is @var{columns}.
@ -1516,12 +1612,12 @@ the frame. The element @var{right} of the value is one more than the
rightmost column used by @var{window}, and @var{bottom} is one more than
the bottommost row used by @var{window} and its mode-line.
When you have side-by-side windows, the right edge value for a window
with a neighbor on the right includes the width of the separator between
the window and that neighbor. This separator may be a column of
@samp{|} characters or it may be a scroll bar. Since the width of the
window does not include this separator, the width does not equal the
difference between the right and left edges in this case.
If a window has a scroll bar, the right edge value includes the width of
the scroll bar. Otherwise, if the window has a neighbor on the right,
its right edge value includes the width of the separator line between
the window and that neighbor. Since the width of the window does not
include this separator, the width does not usually equal the difference
between the right and left edges.
Here is the result obtained on a typical 24-line terminal with just one
window:
@ -1538,14 +1634,12 @@ The bottom edge is at line 23 because the last line is the echo area.
If @var{window} is at the upper left corner of its frame, then
@var{bottom} is the same as the value of @code{(window-height)},
@var{right} is almost the same as the value of
@code{(window-width)}@footnote{They are not exactly equal because
@var{right} includes the vertical separator line or scroll bar, while
@code{(window-width)} does not.}, and @var{top} and @var{left} are zero.
For example, the edges of the following window are @w{@samp{0 0 5 8}}.
Assuming that the frame has more than 8 columns, the last column of the
window (column 7) holds a border rather than text. The last row (row 4)
holds the mode line, shown here with @samp{xxxxxxxxx}.
@var{right} is almost the same as the value of @code{(window-width)},
and @var{top} and @var{left} are zero. For example, the edges of the
following window are @w{@samp{0 0 8 5}}. Assuming that the frame has
more than 8 columns, the last column of the window (column 7) holds a
border rather than text. The last row (row 4) holds the mode line,
shown here with @samp{xxxxxxxxx}.
@example
@group
@ -1561,15 +1655,9 @@ holds the mode line, shown here with @samp{xxxxxxxxx}.
@end group
@end example
When there are side-by-side windows, any window not at the right edge of
its frame has a separator in its last column or columns. The separator
counts as one or two columns in the width of the window. A window never
includes a separator on its left, since that belongs to the window to
the left.
In the following example, let's suppose that the frame is 7
columns wide. Then the edges of the left window are @w{@samp{0 0 4 3}}
and the edges of the right window are @w{@samp{4 0 7 3}}.
and the edges of the right window are @w{@samp{4 0 8 3}}.
@example
@group
@ -1610,6 +1698,13 @@ If the requested size would exceed that of the window's frame, then the
function makes the window occupy the entire height (or width) of the
frame.
If there are various other windows from which lines or columns can be
stolen, and some of them specify fixed size (using
@code{window-size-fixed}, see below), they are left untouched while
other windows are ``robbed.'' If it would be necessary to alter the
size of a fixed-size window, @code{enlarge-window} gets an error
instead.
If @var{size} is negative, this function shrinks the window by
@minus{}@var{size} lines or columns. If that makes the window smaller
than the minimum size (@code{window-min-height} and
@ -1652,10 +1747,11 @@ It could be defined as follows:
@end example
@end deffn
@deffn Command shrink-window-if-larger-than-buffer window
@deffn Command shrink-window-if-larger-than-buffer &optional window
This command shrinks @var{window} to be as small as possible while still
showing the full contents of its buffer---but not less than
@code{window-min-height} lines.
@code{window-min-height} lines. If @var{window} is not given,
it defaults to the selected window.
However, the command does nothing if the window is already too small to
display the whole text of the buffer, or if part of the contents are
@ -1663,6 +1759,35 @@ currently scrolled off screen, or if the window is not the full width of
its frame, or if the window is the only window in its frame.
@end deffn
@tindex window-size-fixed
@defvar window-size-fixed
If this variable is non-@code{nil}, in any given buffer,
then the size of any window displaying the buffer remains fixed
unless you explicitly change it or Emacs has no other choice.
(This feature is new in Emacs 21.)
If the value is @code{height}, then only the window's height is fixed;
if the value is @code{width}, then only the window's width is fixed.
Any other non-@code{nil} value fixes both the width and the height.
The usual way to use this variable is to give it a buffer-local value in
a particular buffer. That way, the windows (but usually there is only
one) displaying that buffer have fixed size.
Explicit size-change functions such as @code{enlarge-window}
get an error if they would have to change a window size which is fixed.
Therefore, when you want to change the size of such a window,
you should bind @code{window-size-fixed} to @code{nil}, like this:
@example
(let ((window-size-fixed nil))
(enlarge-window 10))
@end example
Note that changing the frame size will change the size of a
fixed-size window, if there is no other alternative.
@end defvar
@cindex minimum window size
The following two variables constrain the window-size-changing
functions to a minimum height and width.
@ -1721,11 +1846,14 @@ window.
@item mode-line
The coordinates are in the mode line of @var{window}.
@item vertical-split
@item header-line
The coordinates are in the header line of @var{window}.
@item vertical-line
The coordinates are in the vertical line between @var{window} and its
neighbor to the right. This value occurs only if the window doesn't
have a scroll bar; positions in a scroll bar are considered outside the
window.
window for these purposes.
@item nil
The coordinates are not in any part of @var{window}.
@ -1750,8 +1878,8 @@ configuration previously saved.
configuration instead of a window configuration. @xref{Frame
Configurations}.
@defun current-window-configuration
This function returns a new object representing the selected frame's
@defun current-window-configuration &optional frame
This function returns a new object representing @var{frame}'s
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
@ -1759,16 +1887,20 @@ 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.
If @var{frame} is omitted, the selected frame is used.
@end defun
@defun set-window-configuration configuration
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 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}
specified by @var{configuration}, for the frame that @var{configuration}
was created for.
The argument @var{configuration} must be a value that was previously
returned by @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.
@ -1913,7 +2045,7 @@ This function sets @var{window}'s end trigger position at
@var{position}.
@end defun
@defun window-redisplay-end-trigger window
@defun window-redisplay-end-trigger &optional window
@tindex window-redisplay-end-trigger
This function returns @var{window}'s current end trigger position.
@end defun