anywhere else); if a particular value does get collected, the
corresponding association is removed from the hash table.
-If @var{weak} is @code{key-or-value}, associations are removed from the
-hash table when either their key or their value part would be collected
-as garbage, not counting references to the key and value from weak hash
-tables. Likewise, if @var{weak} is @code{key-and-value}, associations
-are removed from the hash table when both their key and value would be
-collected as garbage, again not considering references to the key and
-value from weak hash tables.
+If @var{weak} is @code{key-or-value} or @code{t}, the hash table does
+not protect either keys or values from garbage collection; if either
+one is collected as garbage, the association is removed.
+
+If @var{weak} is @code{key-and-value}, associations are removed from
+the hash table when both their key and value would be collected as
+garbage, again not considering references to the key and value from
+weak hash tables.
The default for @var{weak} is @code{nil}, so that all keys and values
referenced in the hash table are preserved from garbage collection. If
The specified functions are stored in the property list of @var{name}
under the property @code{hash-table-test}; the property value's form is
@code{(@var{test-fn} @var{hash-fn})}.
+@end defun
+
+@tindex sxhash
+@defun sxhash obj
+This function returns a hash code for Lisp object @var{obj}.
+This is an integer which reflects the contents of @var{obj}
+and the other Lisp objects it points to.
+
+If two objects @var{obj1} and @var{obj2} are equal, then @code{(sxhash
+@var{obj1})} and @code{(sxhash @var{obj2})} are the same integer.
+
+If the two objects are not equal, the values returned by @code{sxhash}
+are usually different, but not always; but once in a rare while, by
+luck, you will encounter two distinct-looking objects that give the same
+result from @code{sxhash}.
+@end defun
-This example creates a hash table whose keys are strings that are
+ This example creates a hash table whose keys are strings that are
compared case-insensitively.
@example
(make-hash-table :test 'case-fold)
@end example
-@end defun
-@tindex sxhash
-@defun sxhash obj
-This function returns a hash code for Lisp object @var{obj}.
-This is an integer which reflects the contents of @var{obj}
-and the other Lisp objects it points to.
+ Here is how you could define a hash table test equivalent to the
+predefined test value @code{equal}. The keys can be any Lisp object,
+and equal-looking objects are considered the same key.
-If two objects @var{obj1} and @var{obj2} are equal, then @code{(sxhash
-@var{obj1})} and @code{(sxhash @var{obj2})} are the same integer.
+@example
+(define-hash-table-test 'contents-hash 'equal 'sxhash)
-If the two objects are not equal, the values returned by @code{sxhash}
-are usually different, but not always; but once in a rare while, by
-luck, you will encounter two distinct-looking objects that give the same
-result from @code{sxhash}.
-@end defun
+(make-hash-table :test 'contents-hash)
+@end example
@node Other Hash
@section Other Hash Table Functions
@end defun
@defun last list &optional n
-This function reruns the last link of the given @var{list}. The
+This function returns the last link of @var{list}. The
@code{car} of this link is the list's last element. If @var{list} is
null, @code{nil} is returned. If @var{n} is non-nil the
@var{n}-th-to-last link is returned instead, or the whole @var{list} if
This macro provides an alternative way to write
@code{(setq @var{listname} (cons @var{newelt} @var{listname}))}.
It is new in Emacs 21.
+
+@example
+(setq l '(a b))
+ @result{} (a b)
+(push 'c l)
+ @result{} (c a b)
+l
+ @result{} (c a b)
+@end example
@end defmac
@defun list &rest objects
@end defun
@defun make-list length object
-This function creates a list of length @var{length}, in which all the
-elements have the identical value @var{object}. Compare
-@code{make-list} with @code{make-string} (@pxref{Creating Strings}).
+This function creates a list of @var{length} elements, in which each
+element is @var{object}. Compare @code{make-list} with
+@code{make-string} (@pxref{Creating Strings}).
@example
@group
(make-list 0 'pigs)
@result{} nil
@end group
+@group
+(setq l (make-list 3 '(a b))
+ @result{} ((a b) (a b) (a b))
+(eq (car l) (cadr l))
+ @result{} t
+@end group
@end example
@end defun
@example
@group
-(setq x '(1 2 3 4))
- @result{} (1 2 3 4)
+(setq x '(a b c))
+ @result{} (a b c)
@end group
@group
x
- @result{} (1 2 3 4)
+ @result{} (a b c)
(nreverse x)
- @result{} (4 3 2 1)
+ @result{} (c b a)
@end group
@group
;; @r{The cons cell that was first is now last.}
x
- @result{} (1)
+ @result{} (a)
@end group
@end example
@example
@group
-'((pine . cones)
- (oak . acorns)
- (maple . seeds))
+((pine . cones)
+ (oak . acorns)
+ (maple . seeds))
@end group
@end example
Sometimes it is better to design an alist to store the associated
value in the @sc{car} of the @sc{cdr} of the element. Here is an
-example:
+example of such an alist:
@example
-'((rose red) (lily white) (buttercup yellow))
+((rose red) (lily white) (buttercup yellow))
@end example
@noindent
@end smallexample
@end defun
-@defun assoc-default key alist test default
+@defun assoc-default key alist &optional test default
This function searches @var{alist} for a match for @var{key}. For each
element of @var{alist}, it compares the element (if it is an atom) or
the element's @sc{car} (if it is a cons) against @var{key}, by calling
@defun assq-delete-all key alist
@tindex assq-delete-all
This function deletes from @var{alist} all the elements whose @sc{car}
-is @code{eq} to @var{key}. It returns the modified alist.
+is @code{eq} to @var{key}. It returns @var{alist}, modified
+in this way. Note that it modifies the original list structure
+of @var{alist}.
@example
(assq-delete-all 'foo
Certain Emacs commands set the mark; other editing commands do not
affect it, so the mark remains where you set it last. Each Emacs
buffer has its own mark, and setting the mark in one buffer has no
-effect on other buffers' marks. When you return to a buffer that had
-been selected previously, its mark is at the same place as before.
+effect on other buffers' marks. When you return to a buffer that was
+current earlier, its mark is at the same place as before.
The ends of the region are always point and the mark. It doesn't
matter which of them was put in its current place first, or which one
@itemize @bullet
@item
To set the mark, type @kbd{C-@key{SPC}} (@code{set-mark-command}).
-This makes the mark active; as you move point, you will see the
-highlighted region grow and shrink.
+This makes the mark active and thus begins highlighting of the region.
+As you move point, you will see the highlighted region grow and
+shrink.
@item
The mouse commands for specifying the mark also make it active. So do
region active again by typing @kbd{C-x C-x}.
@item
-Commands like @kbd{M->} and @kbd{C-s} that ``leave the mark behind'' in
+Commands like @kbd{M->} and @kbd{C-s}, that ``leave the mark behind'' in
addition to some other primary purpose, do not activate the new mark.
You can activate the new region by executing @kbd{C-x C-x}
(@code{exchange-point-and-mark}).
window highlights its region (@pxref{Windows}). However, if the
variable @code{highlight-nonselected-windows} is non-@code{nil}, then
each window highlights its own region (provided that Transient Mark mode
-is enabled and the mark in the buffer's window is active).
+is enabled and the mark in the window's buffer is active).
When Transient Mark mode is not enabled, every command that sets the
mark also activates it, and nothing ever deactivates it.
@table @kbd
@item M-@@
-Set mark after the end of next word (@code{mark-word}). This command and
+Set mark after end of next word (@code{mark-word}). This command and
the following one do not move point.
@item C-M-@@
-Set mark after the end of following balanced expression (@code{mark-sexp}).
+Set mark after end of following balanced expression (@code{mark-sexp}).
@item M-h
-Put region around the current paragraph (@code{mark-paragraph}).
+Put region around current paragraph (@code{mark-paragraph}).
@item C-M-h
-Put region around the current defun (@code{mark-defun}).
+Put region around current defun (@code{mark-defun}).
@item C-x h
Put region around the entire buffer (@code{mark-whole-buffer}).
@item C-x C-p
-Put region around the current page (@code{mark-page}).
+Put region around current page (@code{mark-page}).
@end table
@kbd{M-@@} (@code{mark-word}) puts the mark at the end of the next
the region so you can indent, case-convert, or kill a whole paragraph.
@kbd{C-M-h} (@code{mark-defun}) similarly puts point before, and the
-mark after, the current or following major top-level definition, or
+mark after, the current (or following) major top-level definition, or
defun (@pxref{Moving by Defuns}). @kbd{C-x C-p} (@code{mark-page})
puts point before the current page, and mark at the end
(@pxref{Pages}). The mark goes after the terminating page delimiter
-(to include it), while point goes after the preceding page delimiter
-(to exclude it). A numeric argument specifies a later page (if
-positive) or an earlier page (if negative) instead of the current
-page.
+(to include it in the region), while point goes after the preceding
+page delimiter (to exclude it). A numeric argument specifies a later
+page (if positive) or an earlier page (if negative) instead of the
+current page.
Finally, @kbd{C-x h} (@code{mark-whole-buffer}) sets up the entire
buffer as the region, by putting point at the beginning and the mark at
@vindex resize-mini-windows
The minibuffer window expands vertically as necessary to hold the
-text that you put in the minibuffer if @code{resize-mini-windows} is
+text that you put in the minibuffer, if @code{resize-mini-windows} is
non-@code{nil}. If @code{resize-mini-windows} is @code{t}, the window
is always resized to fit the size of the text it displays. If
@code{resize-mini-windows} is the symbol @code{grow-only}, the window
-is enlarged when the size of displayed text grows, but never reduced
-in size until it becomes empty, at which point it shrinks back to its
-normal size.
+grows when the size of displayed text increases, but shrinks (back to
+the normal size) only when the minibuffer becomes inactive.
@vindex max-mini-window-height
The variable @code{max-mini-window-height} controls the maximum
If while in the minibuffer you issue a command that displays help text
of any sort in another window, you can use the @kbd{C-M-v} command while
in the minibuffer to scroll the help text. This lasts until you exit
-the minibuffer. This feature is especially useful if the
-minibuffer gives you a list of possible completions. @xref{Other Window}.
+the minibuffer. This feature is especially useful when you display
+a buffer listing possible completions. @xref{Other Window}.
@vindex enable-recursive-minibuffers
Emacs normally disallows most commands that use the minibuffer while
type @key{SPC}, it finds that the completion is @samp{auto-fill-mode},
but it stops completing after @samp{fill-}. This gives
@samp{auto-fill-}. Another @key{SPC} at this point completes all the
-way to @samp{auto-fill-mode}. Typing @key{SPC} in the minibuffer when
-completion is available runs the command
-@code{minibuffer-complete-word}.
+way to @samp{auto-fill-mode}. The command that implements this
+behavior is called @code{minibuffer-complete-word}.
Here are some commands you can use to choose a completion from a
window that displays a list of completions:
lists of completions---those always mention all possible completions.
@vindex completion-auto-help
- Normally, a completion command that finds that the next character is
-undetermined automatically displays a list of all possible
+ Normally, a completion command that cannot determine even one
+additional character automatically displays a list of all possible
completions. If the variable @code{completion-auto-help} is set to
-@code{nil}, this does not happen, and you must type @kbd{?} to display
-the possible completions.
+@code{nil}, this automatic display is disabled, so you must type
+@kbd{?} to display the list of completions.
@cindex Partial Completion mode
@vindex partial-completion-mode
A numeric argument, as in @kbd{M-1 M-!}, says to insert terminal
output into the current buffer instead of a separate buffer. It puts
point before the output, and sets the mark after the output. For
-instance, @kbd{M-1 M-! gunzip < foo.gz @key{RET}} would insert the
+instance, @kbd{M-1 M-! gunzip < foo.gz @key{RET}} would insert the
uncompressed equivalent of @file{foo.gz} into the current buffer.
If the shell command line ends in @samp{&}, it runs asynchronously.
face @code{comint-highlight-prompt}. This makes it easier to see
previous input lines in the buffer. @xref{Faces}.
- To make multiple subshells invoke @kbd{M-x shell} with a prefix
-argument (e.g. @kbd{C-u M-x shell}), which will cause it to prompt for
-a buffer name, and create (or reuse) a subshell in that buffer. All
-subshells in different buffers run independently and in parallel.
+ To make multiple subshells, you can invoke @kbd{M-x shell} with a
+prefix argument (e.g. @kbd{C-u M-x shell}), which will read a buffer
+name and create (or reuse) a subshell in that buffer. You can also
+rename the @samp{*shell*} buffer using @kbd{M-x rename-uniquely}, then
+then create a new @samp{*shell*} buffer using plain @kbd{M-x shell}.
+All the subshells in different buffers run independently and in
+parallel.
@vindex explicit-shell-file-name
@cindex environment variables for subshells
@noindent
This tells Emacs to visit each of the specified files; if you specify a
line number for a certain file, Emacs moves to that line in the file.
-If you specify a column number for a file, Emacs moves to that column
-in the file.
+If you specify a column number as well, Emacs puts point on that column
+in the line.
Ordinarily, @code{emacsclient} does not return until you use the
@kbd{C-x #} command on each of these buffers. When that happens,
If you modify the @env{LC_ALL}, @env{LC_CTYPE}, or @env{LANG}
environment variables while running Emacs, you may want to invoke the
-@code{set-locale-environment} function afterwards to re-adjust the
+@code{set-locale-environment} function afterwards to readjust the
language environment from the new locale.
@vindex locale-preferred-coding-systems
input methods.
The simplest kind of input method works by mapping ASCII letters
-into another alphabet; this allows you to type characters that your
-keyboard doesn't support directly. This is how the Greek and Russian
-input methods work.
+into another alphabet; this allows you to use one other alphabet
+instead of ASCII. The Greek and Russian input methods
+work this way.
A more powerful technique is composition: converting sequences of
characters into one letter. Many European input methods use composition
methods, first you enter the phonetic spelling of a Chinese word (in
input method @code{chinese-py}, among others), or a sequence of
portions of the character (input methods @code{chinese-4corner} and
-@code{chinese-sw}, and others). One phonetic spelling typically
-corresponds to many different Chinese characters. You select the one
+@code{chinese-sw}, and others). One input sequence typically
+corresponds to many possible Chinese characters. You select the one
you mean using keys such as @kbd{C-f}, @kbd{C-b}, @kbd{C-n},
@kbd{C-p}, and digits, which have special meanings in this situation.
@key{TAB} in these Chinese input methods displays a buffer showing
all the possible characters at once; then clicking @kbd{Mouse-2} on
one of them selects that alternative. The keys @kbd{C-f}, @kbd{C-b},
-@kbd{C-n}, @kbd{C-p}, and digits continue to work also. When this
-buffer is visible, @kbd{C-n} and @kbd{C-p} move the current
-alternative to a different row.
+@kbd{C-n}, @kbd{C-p}, and digits continue to work as usual, but they
+do the highlighting in the buffer showing the possible characters,
+rather than in the echo area.
In Japanese input methods, first you input a whole word using
phonetic spelling; then, after the word is in the buffer, Emacs
If you use a coding system that specifies the end-of-line conversion
type, such as @code{iso-8859-1-dos}, what this means is that Emacs
should attempt to recognize @code{iso-8859-1} with priority, and should
-use DOS end-of-line conversion if it recognizes @code{iso-8859-1}.
+use DOS end-of-line conversion when it does recognize @code{iso-8859-1}.
@vindex file-coding-system-alist
Sometimes a file name indicates which coding system to use for the
local variables list at the end (@pxref{File Variables}). You do this
by defining a value for the ``variable'' named @code{coding}. Emacs
does not really have a variable @code{coding}; instead of setting a
-variable, it uses the specified coding system for the file. For
+variable, this uses the specified coding system for the file. For
example, @samp{-*-mode: C; coding: latin-1;-*-} specifies use of the
-Latin-1 coding system, as well as C mode. If you specify the coding
+Latin-1 coding system, as well as C mode. When you specify the coding
explicitly in the file, that overrides
@code{file-coding-system-alist}.
cannot be encoded with the coding system that will be used to save the
buffer. For example, you could start with an ASCII file and insert a
few Latin-1 characters into it, or you could edit a text file in
-Polish encoded in @code{iso-8859-2} and add to it translations of
-several Polish words into Russian. When you save the buffer, Emacs
-cannot use the current value of @code{buffer-file-coding-system},
-because the characters you added cannot be encoded by that coding
-system.
+Polish encoded in @code{iso-8859-2} and add some Russian words to it.
+When you save the buffer, Emacs cannot use the current value of
+@code{buffer-file-coding-system}, because the characters you added
+cannot be encoded by that coding system.
When that happens, Emacs tries the most-preferred coding system (set
by @kbd{M-x prefer-coding-system} or @kbd{M-x
projects / emacs.git / commitdiff