Commit 477b9eaf authored by Glenn Morris's avatar Glenn Morris

Merge from origin/emacs-27

05089a4d (origin/emacs-27) Tweak wording re constant variables
a1040861 Tweak setcar-related wording
751510f8 * lisp/image-mode.el: Add prefix key 's' and reduce depend...
9261a219 * doc/emacs/windows.texi (Window Convenience): Decribe mor...
e1d42da0 Fix mutability glitches reported by Drew Adams
5805df74 Improve mutability doc
dca35b31 Improve mutability documentation
81e7d7f1 Document that quoting yields constants
5734339f * doc/lispref/keymaps.texi (Extended Menu Items, Easy Menu...
14a570af Remove #' and function quoting from lambda forms in manual
d5ec18c6 * src/regex-emacs.c (re_match_2_internal): Rework comment ...
4df8a611 Add new node "Image Mode" to Emacs Manual.
d7d5ee6c ; Fix a typo in cmdargs.texi (bug#40701)
5e9db48f * doc/lispref/display.texi (Customizing Bitmaps): Fix typo.
eebfb72c Document constant vs mutable objects better
6c187ed6 Improve documentation of 'sort-lines'
52288f4b Mention 'spam-stat-process-directory-age' in the documenta...
067b0705 ; Fix some typos and doc issues (bug#40695)

# Conflicts:
#	etc/NEWS
parents 80f04b5d 05089a4d
Pipeline #5330 failed with stage
in 57 minutes and 27 seconds
......@@ -11660,7 +11660,7 @@
Mention the Emacs exit code in batch mode
* doc/lispref/os.texi (Batch Mode): Mention what the exit code is
if an error is signalled (bug#31552).
if an error is signaled (bug#31552).
2019-10-12 Kaushal Modi <kaushal.modi@gmail.com>
......@@ -15059,7 +15059,7 @@
* lisp/image/exif.el (exif-parse-buffer): New function.
(exif-orientation): Ditto.
(exif-error): New error symbol, and adjust all error signalling to
(exif-error): New error symbol, and adjust all error signaling to
only use that signal.
2019-09-22 Andreas Schwab <schwab@linux-m68k.org>
......@@ -25100,7 +25100,7 @@
* lisp/json.el (json-read): Try to clarify what's returned (bug#34242).
(json-encode): Refer to `json-read' about what the input is and
say what error is signalled.
say what error is signaled.
2019-07-09 Lars Ingebrigtsen <larsi@gnus.org>
......@@ -26971,7 +26971,7 @@
help-C-file-name shouldn't error out if we can't find the name
* lisp/help-fns.el (help-C-file-name): Make help-C-file-name
return nil instead of signalling an error if we can't find the
return nil instead of signaling an error if we can't find the
file name (bug#17250).
2019-06-26 Stefan Monnier <monnier@iro.umontreal.ca>
......@@ -34107,7 +34107,7 @@
Remove unused internal function completion-pcm--optimize-pattern
* lisp/minibuffer.el (completion-pcm--optimize-pattern): Remove
unused internal function (that signalled a compilation warning).
unused internal function (that signaled a compilation warning).
2019-05-16 Stefan Monnier <monnier@iro.umontreal.ca>
......@@ -40134,10 +40134,10 @@
2019-03-30 Mattias Engdegård <mattiase@acm.org>
Release regexp before signalling overflow error
Release regexp before signaling overflow error
* src/search.c (looking_at_1, search_buffer_re): Unfreeze the regexp
buffer before signalling a matcher overflow, since the error
buffer before signaling a matcher overflow, since the error
processing may require quite some regexp use as well (Bug#34910).
2019-03-30 Mattias Engdegård <mattiase@acm.org>
......@@ -88604,7 +88604,7 @@
Tweak Fdocumentation's error for an undefined function
* src/doc.c (Fdocumentation): Restore the pre-25 behavior
of signalling a void-function error for an undefined function.
of signaling a void-function error for an undefined function.
This seems cleaner than Emacs 25's "invalid-function: nil" error,
which was (probably) an unintended consequence of changes to
Findirect_function.
......@@ -81,7 +81,7 @@ the ones that are not reproducible on the current release.
* New bug triage process
The goal of the new bug triage process is similar to the backlog triage process,
except that the focus is on prioritizing the bug, and making sure it is has
except that the focus is on prioritizing the bug, and making sure it has
necessary information for others to act on.
For each new bug, ask the following questions:
......
......@@ -340,7 +340,7 @@ initialization file (@pxref{Resources}).
@opindex --quick
Start Emacs with minimum customizations. This is similar to using
@samp{-q}, @samp{--no-site-file}, @samp{--no-site-lisp},
@samp{--no-x-resources}, and @samp{--no-splash} together..
@samp{--no-x-resources}, and @samp{--no-splash} together.
@item -daemon
@opindex -daemon
......
......@@ -1416,7 +1416,8 @@ C-c}.
Image-Dired is a facility for browsing image files. It provides viewing
the images either as thumbnails or in full size, either inside Emacs
or through an external viewer.
or through an external viewer. This is different from Image mode
(@pxref{Image Mode}) for visiting an image file in the Emacs buffer.
@kindex C-t d @r{(Image-Dired)}
@findex image-dired-display-thumbs
......
......@@ -455,7 +455,8 @@ File Handling
* Remote Files:: Accessing files on other machines.
* Quoted File Names:: Quoting special characters in file names.
* File Name Cache:: Completion against a list of files you often use.
* File Conveniences:: Convenience Features for Finding Files.
* File Conveniences:: Convenience features for finding files.
* Image Mode:: Viewing image files.
* Filesets:: Handling sets of files.
Saving Files
......
......@@ -38,7 +38,8 @@ on file directories.
* Remote Files:: Accessing files on other machines.
* Quoted File Names:: Quoting special characters in file names.
* File Name Cache:: Completion against a list of files you often use.
* File Conveniences:: Convenience Features for Finding Files.
* File Conveniences:: Convenience features for finding files.
* Image Mode:: Viewing image files.
* Filesets:: Handling sets of files.
@end menu
......@@ -2088,8 +2089,7 @@ of the cache with the @code{file-cache-display} command.
@section Convenience Features for Finding Files
In this section, we introduce some convenient facilities for finding
recently-opened files, reading file names from a buffer, and viewing
image files.
recently-opened files, reading file names from a buffer.
@findex recentf-mode
@vindex recentf-mode
......@@ -2108,6 +2108,9 @@ point. Partial Completion mode offers other features extending
@code{find-file}, which can be used with @code{ffap}.
@xref{Completion Options}.
@node Image Mode
@section Viewing Image Files
@findex image-mode
@findex image-toggle-display
@findex image-next-file
......
......@@ -204,8 +204,8 @@ sentences and paragraphs, respectively. These commands work like
A numeric argument to a transpose command serves as a repeat count: it
tells the transpose command to move the character (or word or
expression or line) before or containing point across several other
characters (or words or expressions or lines). For example, @kbd{C-u
3 C-t} moves the character before point forward across three other
characters (or words or expressions or lines). For example, @w{@kbd{C-u
3 C-t}} moves the character before point forward across three other
characters. It would change @samp{f@point{}oobar} into
@samp{oobf@point{}ar}. This is equivalent to repeating @kbd{C-t}
three times. @kbd{C-u - 4 M-t} moves the word before point backward
......@@ -307,10 +307,10 @@ region; @pxref{Disabled Transient Mark}.)
@cindex spell-checking the active region
Similarly, the command @kbd{M-x ispell} performs spell-checking in
the region if one is active, or in the entire buffer otherwise. The
commands @kbd{M-x ispell-buffer} and @kbd{M-x ispell-region}
commands @w{@kbd{M-x ispell-buffer}} and @w{@kbd{M-x ispell-region}}
explicitly perform spell-checking on the entire buffer or the region
respectively. To check spelling in an email message you are writing,
use @kbd{M-x ispell-message}; that command checks the whole buffer,
use @w{@kbd{M-x ispell-message}}; that command checks the whole buffer,
except for material that is indented or appears to be cited from other
messages. @xref{Sending Mail}.
......@@ -368,8 +368,8 @@ wildcard.
@item C-g
@itemx X
Quit interactive spell-checking, leaving point at the word that was
being checked. You can restart checking again afterward with @kbd{C-u
M-$}.
being checked. You can restart checking again afterward with @w{@kbd{C-u
M-$}}.
@item x
Quit interactive spell-checking and move point back to where it was
......@@ -387,8 +387,8 @@ Show the list of options.
(@code{ispell-complete-word}) performs in-buffer completion based on
spelling correction. Insert the beginning of a word, and then type
@kbd{M-@key{TAB}}; this shows a list of completions. (If your
window manager intercepts @kbd{M-@key{TAB}}, type @kbd{@key{ESC}
@key{TAB}} or @kbd{C-M-i}.) Each completion is listed with a digit or
window manager intercepts @kbd{M-@key{TAB}}, type @w{@kbd{@key{ESC}
@key{TAB}}} or @kbd{C-M-i}.) Each completion is listed with a digit or
character; type that digit or character to choose it.
@cindex @code{ispell} program
......@@ -396,7 +396,7 @@ character; type that digit or character to choose it.
Once started, the spell-checker subprocess continues
to run, waiting for something to do, so that subsequent spell-checking
commands complete more quickly. If you want to get rid of the
process, use @kbd{M-x ispell-kill-ispell}. This is not usually
process, use @w{@kbd{M-x ispell-kill-ispell}}. This is not usually
necessary, since the process uses no processor time except when you do
spelling correction.
......@@ -409,7 +409,7 @@ the standard dictionary and your personal dictionary. The standard
dictionary is specified by the variable @code{ispell-local-dictionary}
or, if that is @code{nil}, by the variable @code{ispell-dictionary}.
If both are @code{nil}, the spelling program's default dictionary is
used. The command @kbd{M-x ispell-change-dictionary} sets the
used. The command @w{@kbd{M-x ispell-change-dictionary}} sets the
standard dictionary for the buffer and then restarts the subprocess,
so that it will use a different standard dictionary. Your personal
dictionary is specified by the variable
......@@ -431,8 +431,8 @@ dictionary.
@findex flyspell-mode
Flyspell mode is a minor mode that performs automatic spell-checking
of the text you type as you type it. When it finds a word that it
does not recognize, it highlights that word. Type @kbd{M-x
flyspell-mode} to toggle Flyspell mode in the current buffer. To
does not recognize, it highlights that word. Type @w{@kbd{M-x
flyspell-mode}} to toggle Flyspell mode in the current buffer. To
enable Flyspell mode in all text mode buffers, add
@code{flyspell-mode} to @code{text-mode-hook}. @xref{Hooks}. Note
that, as Flyspell mode needs to check each word across which you move,
......@@ -448,14 +448,14 @@ it with @kbd{mouse-2} (@code{flyspell-correct-word}) to display a menu
of possible corrections and actions. In addition, @kbd{C-.} or
@kbd{@key{ESC}-@key{TAB}} (@code{flyspell-auto-correct-word}) will
propose various successive corrections for the word at point, and
@kbd{C-c $} (@code{flyspell-correct-word-before-point}) will pop up a
@w{@kbd{C-c $}} (@code{flyspell-correct-word-before-point}) will pop up a
menu of possible corrections. Of course, you can always correct the
misspelled word by editing it manually in any way you like.
@findex flyspell-prog-mode
Flyspell Prog mode works just like ordinary Flyspell mode, except
that it only checks words in comments and string constants. This
feature is useful for editing programs. Type @kbd{M-x
flyspell-prog-mode} to enable or disable this mode in the current
feature is useful for editing programs. Type @w{@kbd{M-x
flyspell-prog-mode}} to enable or disable this mode in the current
buffer. To enable this mode in all programming mode buffers, add
@code{flyspell-prog-mode} to @code{prog-mode-hook} (@pxref{Hooks}).
......@@ -227,8 +227,9 @@ left. If you'd like to reverse the direction of horizontal scrolling,
customize the variable @code{mouse-wheel-flip-direction} to a
non-@code{nil} value.
When the mouse pointer is over an image, scrolling the mouse wheel
with the @key{Ctrl} modifier scales the image under the mouse pointer.
When the mouse pointer is over an image in Image mode, @pxref{Image Mode},
scrolling the mouse wheel with the @key{Ctrl} modifier scales the image
under the mouse pointer.
@node Word and Line Mouse
......
......@@ -2883,7 +2883,7 @@ if there is an active region (@pxref{Mark}), the default URL comes
from the region instead, after removing any whitespace from it. The
command then creates a new buffer with the embedded browser showing
the specified URL. The buffer is put in the Xwidget-WebKit mode
(similar to Image mode, @pxref{File Conveniences}), which provides
(similar to Image mode, @pxref{Image Mode}), which provides
one-key commands for scrolling the widget, changing its size, and
reloading it. Type @w{@kbd{C-h b}} in that buffer to see the key
bindings.
......
......@@ -586,13 +586,25 @@ buffer. @xref{Follow Mode}.
@cindex directional window selection
@findex windmove-right
@findex windmove-default-keybindings
@findex windmove-display-default-keybindings
@findex windmove-delete-default-keybindings
@findex windmove-swap-states-in-direction
The Windmove package defines commands for moving directionally
between neighboring windows in a frame. @kbd{M-x windmove-right}
selects the window immediately to the right of the currently selected
one, and similarly for the left, up, and down
counterparts. @w{@kbd{M-x windmove-default-keybindings}} binds these
commands to @kbd{S-right} etc.; doing so disables shift selection for
those keys (@pxref{Shift Selection}).
one, and similarly for the left, up, and down counterparts.
@w{@kbd{M-x windmove-default-keybindings}} binds these commands to
@kbd{S-right} etc.; doing so disables shift selection for those keys
(@pxref{Shift Selection}). In the same way as keybindings can be
defined for commands that select windows directionally, you can use
@w{@kbd{M-x windmove-display-default-keybindings}} to define
keybindings for commands that specify in what direction to display the
window for the buffer that the next command is going to display.
Also there is @w{@kbd{M-x windmove-delete-default-keybindings}} to
define keybindings for commands that delete windows directionally, and
@w{@kbd{M-x windmove-swap-states-in-direction}} that define
keybindings for commands that swap the window contents of the selected
window with the window in the specified direction.
The command @kbd{M-x compare-windows} lets you compare the text
shown in different windows. @xref{Comparing Files}.
......
......@@ -2329,7 +2329,7 @@ area.
@cindex @samp{bind} defined
There are several ways by which a variable can be given a value. One of
the ways is to use either the function @code{set} or the function
the ways is to use either the function @code{set} or the special form
@code{setq}. Another way is to use @code{let} (@pxref{let}). (The
jargon for this process is to @dfn{bind} a variable to a value.)
......@@ -4517,7 +4517,7 @@ number; it will be printed as the character with that @sc{ascii} code.
@item setq
@itemx set
The @code{setq} function sets the value of its first argument to the
The @code{setq} special form sets the value of its first argument to the
value of the second argument. The first argument is automatically
quoted by @code{setq}. It does the same for succeeding pairs of
arguments. Another function, @code{set}, takes only two arguments and
......@@ -7317,11 +7317,21 @@ which leave the original list as it was. One way to find out how this
works is to experiment. We will start with the @code{setcar} function.
@need 1200
@cindex constant lists
@cindex mutable lists
First, we can make a list and then set the value of a variable to the
list, using the @code{setq} function. Here is a list of animals:
list, using the @code{setq} special form. Because we intend to use
@code{setcar} to change the list, this @code{setq} should not use the
quoted form @code{'(antelope giraffe lion tiger)}, as that would yield
a list that is part of the program and bad things could happen if we
tried to change part of the program while running it. Generally
speaking an Emacs Lisp program's components should be constant (or
unchanged) while the program is running. So we instead construct an
animal list that is @dfn{mutable} (or changeable) by using the
@code{list} function, as follows:
@smallexample
(setq animals '(antelope giraffe lion tiger))
(setq animals (list 'antelope 'giraffe 'lion 'tiger))
@end smallexample
@noindent
......@@ -7398,7 +7408,7 @@ To see how this works, set the value of the variable to a list of
domesticated animals by evaluating the following expression:
@smallexample
(setq domesticated-animals '(horse cow sheep goat))
(setq domesticated-animals (list 'horse 'cow 'sheep 'goat))
@end smallexample
@need 1200
......@@ -8846,7 +8856,7 @@ and then find the value of @code{trees}:
@smallexample
@group
(setq trees '(maple oak pine birch))
(setq trees (list 'maple 'oak 'pine 'birch))
@result{} (maple oak pine birch)
@end group
......@@ -9366,7 +9376,7 @@ For example:
@smallexample
@group
(setq triple '(1 2 3))
(setq triple (list 1 2 3))
(setcar triple '37)
......@@ -9547,7 +9557,7 @@ part of which is the address of the next pair. The very last box
points to the symbol @code{nil}, which marks the end of the list.
@need 1200
When a variable is set to a list with a function such as @code{setq},
When a variable is set to a list with an operation such as @code{setq},
it stores the address of the first box in the variable. Thus,
evaluation of the expression
......@@ -17092,7 +17102,7 @@ reminders.
@cindex Mail aliases
@noindent
This @code{setq} command sets the value of the variable
This @code{setq} sets the value of the variable
@code{mail-aliases} to @code{t}. Since @code{t} means true, the line
says, in effect, ``Yes, use mail aliases.''
......@@ -17130,8 +17140,8 @@ The following turns off Indent Tabs mode:
@end smallexample
Note that this line uses @code{setq-default} rather than the
@code{setq} command that we have seen before. The @code{setq-default}
command sets values only in buffers that do not have their own local
@code{setq} that we have seen before; @code{setq-default}
sets values only in buffers that do not have their own local
values for the variable.
@ifinfo
......
......@@ -370,9 +370,9 @@ definitions of @code{local-abbrev-table} and @code{text-mode-abbrev-table}.
(funcall expand))))
(add-hook 'foo-mode-hook
#'(lambda ()
(add-function :around (local 'abbrev-expand-function)
#'foo-mode-abbrev-expand-function)))
(lambda ()
(add-function :around (local 'abbrev-expand-function)
#'foo-mode-abbrev-expand-function)))
@end smallexample
@node Standard Abbrev Tables
......
......@@ -807,7 +807,7 @@ If you just want to automatically auto-revert every
@example
(setq-local buffer-stale-function
#'(lambda (&optional noconfirm) 'fast))
(lambda (&optional noconfirm) 'fast))
@end example
@noindent
......
......@@ -4358,7 +4358,7 @@ height.
@end defun
@defun destroy-fringe-bitmap bitmap
This function destroy the fringe bitmap identified by @var{bitmap}.
This function destroys the fringe bitmap identified by @var{bitmap}.
If @var{bitmap} identifies a standard fringe bitmap, it actually
restores the standard definition of that bitmap, instead of
eliminating it entirely.
......@@ -6926,7 +6926,7 @@ end of the buffer continues from the other end. If
is displayed. Any button with a non-@code{nil} @code{skip} property
is skipped over. Returns the button found, and signals an error if no
buttons can be found. If @var{no-error} in non-@code{nil}, return nil
instead of signalling the error.
instead of signaling the error.
@end deffn
@deffn Command backward-button n &optional wrap display-message
......@@ -6938,7 +6938,7 @@ end of the buffer continues from the other end. If
is displayed. Any button with a non-@code{nil} @code{skip} property
is skipped over. Returns the button found, and signals an error if no
buttons can be found. If @var{no-error} in non-@code{nil}, return nil
instead of signalling the error.
instead of signaling the error.
@end deffn
@defun next-button pos &optional count-current
......
......@@ -858,7 +858,7 @@ to a non-@code{nil} value.
Here is an example of code that creates a circular structure:
@example
(setq a '(x y))
(setq a (list 'x 'y))
(setcar a a)
@end example
......
......@@ -297,6 +297,7 @@ Lisp Data Types
* Circular Objects:: Read syntax for circular structure.
* Type Predicates:: Tests related to types.
* Equality Predicates:: Tests of equality between any two objects.
* Constants and Mutability:: Whether an object's value can change.
Programming Types
......
......@@ -158,6 +158,12 @@ contents unchanged.
@end group
@end example
A self-evaluating form yields constant conses, vectors and strings, and you
should not attempt to modify their contents via @code{setcar}, @code{aset} or
similar operations. The Lisp interpreter might unify the constants
yielded by your program's self-evaluating forms, so that these
constants might share structure. @xref{Constants and Mutability}.
It is common to write numbers, characters, strings, and even vectors
in Lisp code, taking advantage of the fact that they self-evaluate.
However, it is quite unusual to do this for types that lack a read
......@@ -558,6 +564,8 @@ and vectors.)
@defspec quote object
This special form returns @var{object}, without evaluating it.
The returned value is a constant, and should not be modified.
@xref{Constants and Mutability}.
@end defspec
@cindex @samp{'} for quoting
......@@ -612,10 +620,12 @@ only part of a list, while computing and substituting other parts.
@dfn{Backquote constructs} allow you to quote a list, but
selectively evaluate elements of that list. In the simplest case, it
is identical to the special form @code{quote}
is identical to the special form
@iftex
@code{quote}.
@end iftex
@ifnottex
@code{quote}
(described in the previous section; @pxref{Quoting}).
@end ifnottex
For example, these two forms yield identical results:
......@@ -693,6 +703,9 @@ Here are some examples:
@end group
@end example
If a subexpression of a backquote construct has no substitutions or
splices, it acts like @code{quote} in that it yields constant conses,
vectors and strings that should not be modified.
@node Eval
@section Eval
......
......@@ -970,7 +970,7 @@ string.
@end group
@group
(mapconcat (function (lambda (x) (format "%c" (1+ x))))
(mapconcat (lambda (x) (format "%c" (1+ x)))
"HAL-8000"
"")
@result{} "IBM.9111"
......@@ -2287,7 +2287,7 @@ function) as a generalized variable. @var{setter} can be a symbol in which
case it will be passed to @code{gv-define-simple-setter}, or it can be of the
form @code{(lambda (@var{arg}) @var{body})} in which case that function will
additionally have access to the macro (or function)'s arguments and it will
passed to @code{gv-define-setter}.
be passed to @code{gv-define-setter}.
@end table
......
......@@ -175,49 +175,47 @@ All symbols that have PATTERN in their name are described
in the *Help* buffer."
(interactive "sDescribe symbols matching: ")
(let ((describe-func
(function
(lambda (s)
(lambda (s)
@end group
@group
;; @r{Print description of symbol.}
(if (fboundp s) ; @r{It is a function.}
(princ
(format "%s\t%s\n%s\n\n" s
(if (commandp s)
(let ((keys (where-is-internal s)))
(if keys
(concat
"Keys: "
(mapconcat 'key-description
keys " "))
"Keys: none"))
"Function")
;; @r{Print description of symbol.}
(if (fboundp s) ; @r{It is a function.}
(princ
(format "%s\t%s\n%s\n\n" s
(if (commandp s)
(let ((keys (where-is-internal s)))
(if keys
(concat
"Keys: "
(mapconcat 'key-description
keys " "))
"Keys: none"))
"Function")
@end group
@group
(or (documentation s)
"not documented"))))
(or (documentation s)
"not documented"))))
(if (boundp s) ; @r{It is a variable.}
(if (boundp s) ; @r{It is a variable.}
@end group
@group
(princ
(format "%s\t%s\n%s\n\n" s
(if (custom-variable-p s)
"Option " "Variable")
(princ
(format "%s\t%s\n%s\n\n" s
(if (custom-variable-p s)
"Option " "Variable")
@end group
@group
(or (documentation-property
s 'variable-documentation)
"not documented")))))))
(or (documentation-property
s 'variable-documentation)
"not documented"))))))
sym-list)
@end group
@group
;; @r{Build a list of symbols that match pattern.}
(mapatoms (function
(lambda (sym)
(if (string-match pattern (symbol-name sym))
(setq sym-list (cons sym sym-list))))))
(mapatoms (lambda (sym)
(if (string-match pattern (symbol-name sym))
(setq sym-list (cons sym sym-list)))))
@end group
@group
......
......@@ -1441,10 +1441,10 @@ Here is an example showing a keymap before and after substitution:
@smallexample
@group
(setq map '(keymap
(?1 . olddef-1)
(?2 . olddef-2)
(?3 . olddef-1)))
(setq map (list 'keymap
(cons ?1 olddef-1)
(cons ?2 olddef-2)
(cons ?3 olddef-1)))
@result{} (keymap (49 . olddef-1) (50 . olddef-2) (51 . olddef-1))
@end group
......@@ -2226,14 +2226,11 @@ right value for selecting that button. Clicking on the button should
set the variable so that the button you clicked on becomes selected.
@item :key-sequence @var{key-sequence}
This property specifies which key sequence is likely to be bound to the
same command invoked by this menu item. If you specify a correct key
sequence, that sequence will be preferred over others.
If you specify an incorrect key sequence, it has no effect; before Emacs
displays @var{key-sequence} in the menu, it verifies that
@var{key-sequence} is really equivalent to this menu item. Specifying
@code{nil} for @var{key-sequence} is equivalent to the
This property specifies which key sequence to display as keyboard equivalent.
Before Emacs displays @var{key-sequence} in the menu, it verifies that
@var{key-sequence} is really equivalent to this menu item, so it only
has an effect if you specify a correct key sequence.
Specifying @code{nil} for @var{key-sequence} is equivalent to the
@code{:key-sequence} attribute being absent.
@item :keys @var{string}
......@@ -2916,17 +2913,17 @@ the following:
@table @code
@item :keys @var{keys}
@var{keys} is a keyboard equivalent to the menu item (a string). This
is normally not needed, as keyboard equivalents are computed
@var{keys} is a string to display as keyboard equivalent to the menu item.
This is normally not needed, as keyboard equivalents are computed
automatically. @var{keys} is expanded with
@code{substitute-command-keys} before it is displayed (@pxref{Keys in
Documentation}).
@item :key-sequence @var{keys}
@var{keys} is a hint for speeding up Emacs's first display of the
menu. It should be @code{nil} if you know that the menu item has no keyboard
equivalent; otherwise it should be a string or vector specifying a
keyboard equivalent for the menu item.
@var{keys} is a hint indicating which key sequence to display as
keyboard equivalent, in case the command is bound to several key sequences.
It has no effect if @var{keys} is not bound to same command as this
menu item.
@item :active @var{enable}
@var{enable} is an expression; if it evaluates to @code{nil}, the item
......
......@@ -866,10 +866,15 @@ foo ;; @r{@code{foo} was changed.}
@node Modifying Lists
@section Modifying Existing List Structure
@cindex destructive list operations
@cindex mutable lists
You can modify the @sc{car} and @sc{cdr} contents of a cons cell with the
primitives @code{setcar} and @code{setcdr}. These are destructive
operations because they change existing list structure.
Destructive operations should be applied only to mutable lists,
that is, lists constructed via @code{cons}, @code{list} or similar
operations. Lists created by quoting are constants and should not be
changed by destructive operations. @xref{Constants and Mutability}.
@cindex CL note---@code{rplaca} vs @code{setcar}
@quotation
......@@ -906,7 +911,7 @@ value @var{object}. For example:
@example