Commit c9352587 authored by Chong Yidong's avatar Chong Yidong

Doc updates for several Emacs 24.4 changes.

* doc/lispref/commands.texi (Event Input Misc): Document new arg to
input-pending-p.

* doc/lispref/display.texi (Font Selection): Tweak example.

* doc/lispref/keymaps.texi (Active Keymaps): Re-organize the text.
(Searching Keymaps): Rewrite the pseudo-code for 24.4 changes.
(Controlling Active Maps): Note that set-transient-map uses
overriding-terminal-local-map.

* doc/lispref/nonascii.texi (Specifying Coding Systems): Don't refer to
emacs-mule-dos.
(Lisp and Coding Systems): Describe emacs-mule return value in
modern terms.

* doc/lispref/tips.texi (Coding Conventions): Tweak the coding system tip;
Emacs now uses utf-8 by default for Emacs Lisp source files.

* doc/emacs/glossary.texi (Glossary): Define MULE in modern terms.

* src/keyboard.c (Voverriding_terminal_local_map):
(Voverriding_local_map): Doc fix.

* src/keymap.c (Vemulation_mode_map_alists): Doc fix.
parent ff1c842a
2013-12-25 Chong Yidong <cyd@gnu.org>
* glossary.texi (Glossary): Define MULE in modern terms.
2013-12-25 Xue Fuqiao <xfq.free@gmail.com>
* files.texi (Diff Mode): Add an index.
......
......@@ -953,9 +953,15 @@ another. The usual way to move text is by killing (q.v.@:) it and then
yanking (q.v.@:) it. @xref{Killing}.
@item MULE
MULE refers to the Emacs features for editing multilingual
non-@acronym{ASCII} text using multibyte characters (q.v.).
@xref{International}.
@cindex MULE
Prior to Emacs 23, @acronym{MULE} was the name of a software package
which provided a @dfn{MULtilingual Enhancement} to Emacs, by adding
support for multiple character sets (q.v.). @acronym{MULE} was later
integrated into Emacs, and much of it was replaced when Emacs gained
internal Unicode support in version 23.
Some parts of Emacs that deal with character set support still use the
@acronym{MULE} name. @xref{International}.
@item Multibyte Character
A multibyte character is a character that takes up several bytes in a
......
......@@ -5,7 +5,6 @@
@chapter International Character Set Support
@c This node is referenced in the tutorial. When renaming or deleting
@c it, the tutorial needs to be adjusted. (TUTORIAL.de)
@cindex MULE
@cindex international scripts
@cindex multibyte characters
@cindex encoding of characters
......
2013-12-25 Chong Yidong <cyd@gnu.org>
* keymaps.texi (Active Keymaps): Re-organize the text.
(Searching Keymaps): Rewrite the pseudo-code for 24.4 changes.
(Controlling Active Maps): Note that set-transient-map uses
overriding-terminal-local-map.
* tips.texi (Coding Conventions): Tweak the coding system tip;
Emacs now uses utf-8 by default for Emacs Lisp source files.
* display.texi (Font Selection): Tweak example.
* commands.texi (Event Input Misc): Document new arg to
input-pending-p.
* nonascii.texi (Specifying Coding Systems): Don't refer to
emacs-mule-dos.
(Lisp and Coding Systems): Describe emacs-mule return value in
modern terms.
2013-12-25 Tassilo Horn <tsdh@gnu.org>
* control.texi (Pattern matching case statement): Rephrase lexical
......
......@@ -2739,12 +2739,16 @@ This function converts the string or vector @var{key} to a list of
individual events, which you can put in @code{unread-command-events}.
@end defun
@defun input-pending-p
@defun input-pending-p &optional check-timers
@cindex waiting for command key input
This function determines whether any command input is currently
available to be read. It returns immediately, with value @code{t} if
there is available input, @code{nil} otherwise. On rare occasions it
may return @code{t} when no input is available.
If the optional argument @var{check-timers} is non-@code{nil}, then if
no input is available, Emacs runs any timers which are ready.
@xref{Timers}.
@end defun
@defvar last-input-event
......
......@@ -2962,11 +2962,11 @@ scalable font is enabled for use if its name matches any regular
expression in the list. For example,
@example
(setq scalable-fonts-allowed '("muleindian-2$"))
(setq scalable-fonts-allowed '("iso10646-1$"))
@end example
@noindent
allows the use of scalable fonts with registry @code{muleindian-2}.
allows the use of scalable fonts with registry @code{iso10646-1}.
@end defopt
@defvar face-font-rescale-alist
......
......@@ -622,75 +622,67 @@ string for the keymap. The prompt string should be given for menu keymaps
@node Active Keymaps
@section Active Keymaps
@cindex active keymap
@cindex global keymap
@cindex local keymap
Emacs normally contains many keymaps; at any given time, just a few
of them are @dfn{active}, meaning that they participate in the
interpretation of user input. All the active keymaps are used
together to determine what command to execute when a key is entered.
Normally the active keymaps are the @code{keymap} property keymap,
the keymaps of any enabled minor modes, the current buffer's local
keymap, and the global keymap, in that order. Emacs searches for each
input key sequence in all these keymaps. @xref{Searching Keymaps},
for more details of this procedure.
When the key sequence starts with a mouse event,
the active keymaps are determined based on the
position in that event. If the event happened on a string embedded
with a @code{display}, @code{before-string}, or @code{after-string}
property (@pxref{Special Properties}), the non-@code{nil} map
properties of the string override those of the buffer (if the
underlying buffer text contains map properties in its text properties
or overlays, they are ignored).
The @dfn{global keymap} holds the bindings of keys that are defined
regardless of the current buffer, such as @kbd{C-f}. The variable
@code{global-map} holds this keymap, which is always active.
Each buffer may have another keymap, its @dfn{local keymap}, which
may contain new or overriding definitions for keys. The current
buffer's local keymap is always active except when
@code{overriding-local-map} overrides it. The @code{local-map} text
or overlay property can specify an alternative local keymap for certain
parts of the buffer; see @ref{Special Properties}.
Each minor mode can have a keymap; if it does, the keymap is active
when the minor mode is enabled. Modes for emulation can specify
additional active keymaps through the variable
@code{emulation-mode-map-alists}.
The highest precedence normal keymap comes from the @code{keymap}
text or overlay property. If that is non-@code{nil}, it is the first
keymap to be processed, in normal circumstances.
However, there are also special ways for programs to substitute
other keymaps for some of those. The variable
@code{overriding-local-map}, if non-@code{nil}, specifies a keymap
that replaces all the usual active keymaps except the global keymap.
The very highest precedence keymap comes from
@code{overriding-terminal-local-map}; it operates on a per-terminal basis and
is normally used for modal/transient keybindings.
Emacs contains many keymaps, but at any time only a few keymaps are
@dfn{active}. When Emacs receives user input, it translates the input
event (@pxref{Translation Keymaps}), and looks for a key binding in
the active keymaps.
Usually, the active keymaps are: (i) the keymap specified by the
@code{keymap} property, (ii) the keymaps of enabled minor modes, (iii)
the current buffer's local keymap, and (iv) the global keymap, in that
order. Emacs searches for each input key sequence in all these
keymaps.
Of these ``usual'' keymaps, the highest-precedence one is specified
by the @code{keymap} text or overlay property at point, if any. (For
a mouse input event, Emacs uses the event position instead of point;
@iftex
see the next section for details.)
@end iftex
@ifnottex
@pxref{Searching Keymaps}.)
@end ifnottex
Next in precedence are keymaps specified by enabled minor modes.
These keymaps, if any, are specified by the variables
@code{emulation-mode-map-alists},
@code{minor-mode-overriding-map-alist}, and
@code{minor-mode-map-alist}. @xref{Controlling Active Maps}.
@cindex major mode keymap
Since every buffer that uses the same major mode normally uses the
same local keymap, you can think of the keymap as local to the mode. A
change to the local keymap of a buffer (using @code{local-set-key}, for
example) is seen also in the other buffers that share that keymap.
The local keymaps that are used for Lisp mode and some other major
modes exist even if they have not yet been used. These local keymaps are
the values of variables such as @code{lisp-mode-map}. For most major
modes, which are less frequently used, the local keymap is constructed
only when the mode is used for the first time in a session.
@cindex local keymap
Next in precedence is the buffer's @dfn{local keymap}, containing
key bindings specific to the buffer. The minibuffer also has a local
keymap (@pxref{Intro to Minibuffers}). If there is a @code{local-map}
text or overlay property at point, that specifies the local keymap to
use, in place of the buffer's default local keymap.
The minibuffer has local keymaps, too; they contain various completion
and exit commands. @xref{Intro to Minibuffers}.
@cindex major mode keymap
The local keymap is normally set by the buffer's major mode, and
every buffer with the same major mode shares the same local keymap.
Hence, if you call @code{local-set-key} (@pxref{Key Binding Commands})
to change the local keymap in one buffer, that also affects the local
keymaps in other buffers with the same major mode.
Emacs has other keymaps that are used in a different way---translating
events within @code{read-key-sequence}. @xref{Translation Keymaps}.
@cindex global keymap
Finally, the @dfn{global keymap} contains key bindings that are
defined regardless of the current buffer, such as @kbd{C-f}. It is
always active, and is bound to the variable @code{global-map}.
Apart from the above ``usual'' keymaps, Emacs provides special ways
for programs to make other keymaps active. Firstly, the variable
@code{overriding-local-map} specifies a keymap that replaces the usual
active keymaps, except for the global keymap. Secondly, the
terminal-local variable @code{overriding-terminal-local-map} specifies
a keymap that takes precedence over @emph{all} other keymaps
(including @code{overriding-local-map}); this is normally used for
modal/transient keybindings (the function @code{set-transient-map}
provides a convenient interface for this). @xref{Controlling Active
Maps}, for details.
Making keymaps active is not the only way to use them. Keymaps are
also used in other ways, such as for translating events within
@code{read-key-sequence}. @xref{Translation Keymaps}.
@xref{Standard Keymaps}, for a list of some standard keymaps.
......@@ -727,7 +719,7 @@ If @var{position} is non-@code{nil}, it should be either a buffer
position or an event position like the value of @code{event-start}.
Then the maps consulted are determined based on @var{position}.
An error is signaled if @var{key} is not a string or a vector.
Emacs signals an error if @var{key} is not a string or a vector.
@example
@group
......@@ -741,49 +733,52 @@ An error is signaled if @var{key} is not a string or a vector.
@section Searching the Active Keymaps
@cindex searching active keymaps for keys
After translation of event subsequences (@pxref{Translation
Keymaps}) Emacs looks for them in the active keymaps. Here is a
pseudo-Lisp description of the order and conditions for searching
them:
Here is a pseudo-Lisp summary of how Emacs searches the active
keymaps:
@lisp
(or (@var{find-in} @var{transient-map})
(cond
(overriding-terminal-local-map
(@var{find-in} overriding-terminal-local-map))
(overriding-local-map
(@var{find-in} overriding-local-map))
((or (@var{find-in} (get-char-property (point) 'keymap))
(or (if overriding-terminal-local-map
(@var{find-in} overriding-terminal-local-map))
(if overriding-local-map
(@var{find-in} overriding-local-map)
(or (@var{find-in} (get-char-property (point) 'keymap))
(@var{find-in-any} emulation-mode-map-alists)
(@var{find-in-any} minor-mode-overriding-map-alist)
(@var{find-in-any} minor-mode-map-alist)
(if (get-text-property (point) 'local-map)
(@var{find-in} (get-char-property (point) 'local-map))
(@var{find-in} (current-local-map))))))
(@var{find-in} (current-local-map)))))
(@var{find-in} (current-global-map)))
@end lisp
@noindent
Here, @var{find-in} and @var{find-in-any} are pseudo functions that
search in one keymap and in an alist of keymaps, respectively.
(Searching a single keymap for a binding is called @dfn{key lookup};
see @ref{Key Lookup}.) @var{transient-map} is a pseudo variable that
represents the effect of a @code{set-transient-map} call
(@pxref{Controlling Active Maps}).
search in one keymap and in an alist of keymaps, respectively. Note
that the @code{set-transient-map} function works by setting
@code{overriding-terminal-local-map} (@pxref{Controlling Active
Maps}).
In the above pseudo-code, if a key sequence starts with a mouse
event, that event's position is used instead of point and the current
buffer. Mouse events on an embedded string use non-@code{nil} text
properties from that string instead of the buffer.
When a match is found (@pxref{Key Lookup}), if the binding in the
keymap is a function, the search is over. However if the keymap entry
is a symbol with a value or a string, Emacs replaces the input key
sequences with the variable's value or the string, and restarts the
search of the active keymaps.
The function finally found might also be remapped. @xref{Remapping
Commands}.
event (@pxref{Mouse Events}), that event's position is used instead of
point, and the event's buffer is used instead of the current buffer.
In particular, this affects how the @code{keymap} and @code{local-map}
properties are looked up. If a mouse event occurs on a string
embedded with a @code{display}, @code{before-string}, or
@code{after-string} property (@pxref{Special Properties}), and the
string has a non-@code{nil} @code{keymap} or @code{local-map}
property, that overrides the corresponding property in the underlying
buffer text (i.e., the property specified by the underlying text is
ignored).
When a key binding is found in one of the active keymaps, and that
binding is a command, the search is over---the command is executed.
However, if the binding is a symbol with a value or a string, Emacs
replaces the input key sequences with the variable's value or the
string, and restarts the search of the active keymaps. @xref{Key
Lookup}.
The command which is finally found might also be remapped.
@xref{Remapping Commands}.
@node Controlling Active Maps
@section Controlling the Active Keymaps
......@@ -860,7 +855,6 @@ keymap. @code{use-local-map} returns @code{nil}. Most major mode
commands use this function.
@end defun
@c Emacs 19 feature
@defvar minor-mode-map-alist
@anchor{Definition of minor-mode-map-alist}
This variable is an alist describing keymaps that may or may not be
......@@ -945,7 +939,7 @@ event is run directly by @code{read-event}. @xref{Special Events}.
@end defvar
@defvar emulation-mode-map-alists
This variable holds a list of keymap alists to use for emulations
This variable holds a list of keymap alists to use for emulation
modes. It is intended for modes or packages using multiple minor-mode
keymaps. Each element is a keymap alist which has the same format and
meaning as @code{minor-mode-map-alist}, or a symbol with a variable
......@@ -970,11 +964,9 @@ function is called with no arguments, prior to running each command,
while @var{keymap} is active; it should return non-@code{nil} if
@var{keymap} should stay active.
The transient keymap takes precedence over the ``overriding'' maps
(see above); and unlike them, if no match for a key is found in
@var{keymap}, the key lookup process continues. For a pseudo-Lisp
description of exactly how and when this keymap applies,
@xref{Searching Keymaps}.
This function works by adding and removing @code{keymap} from the
variable @code{overriding-terminal-local-map}, which takes precedence
over all other active keymaps (@pxref{Searching Keymaps}).
@end defun
@node Key Lookup
......
......@@ -1289,17 +1289,18 @@ Sets}) supported by @var{coding-system}. Some coding systems that
support too many character sets to list them all yield special values:
@itemize @bullet
@item
If @var{coding-system} supports all the ISO-2022 charsets, the value
is @code{iso-2022}.
@item
If @var{coding-system} supports all Emacs characters, the value is
@code{(emacs)}.
@item
If @var{coding-system} supports all emacs-mule characters, the value
is @code{emacs-mule}.
@item
If @var{coding-system} supports all Unicode characters, the value is
@code{(unicode)}.
@item
If @var{coding-system} supports all ISO-2022 charsets, the value is
@code{iso-2022}.
@item
If @var{coding-system} supports all the characters in the internal
coding system used by Emacs version 21 (prior to the implementation of
internal Unicode support), the value is @code{emacs-mule}.
@end itemize
@end defun
......@@ -1617,8 +1618,7 @@ of the right way to use the variable:
@example
;; @r{Read the file with no character code conversion.}
;; @r{Assume @acronym{crlf} represents end-of-line.}
(let ((coding-system-for-read 'emacs-mule-dos))
(let ((coding-system-for-read 'no-conversion))
(insert-file-contents filename))
@end example
......
......@@ -223,18 +223,13 @@ only for special-purpose buffers.) People will find Emacs more
coherent if all libraries use the same conventions.
@item
If your program contains non-ASCII characters in string or character
constants, you should make sure Emacs always decodes these characters
the same way, regardless of the user's settings. The easiest way to
do this is to use the coding system @code{utf-8-emacs} (@pxref{Coding
System Basics}), and specify that coding in the @samp{-*-} line or the
The default file coding system for Emacs Lisp source files is UTF-8
(@pxref{Text Representations}). In the rare event that your program
contains characters which are @emph{not} in UTF-8, you should specify
an appropriate coding system in the source file's @samp{-*-} line or
local variables list. @xref{File Variables, , Local Variables in
Files, emacs, The GNU Emacs Manual}.
@example
;; XXX.el -*- coding: utf-8-emacs; -*-
@end example
@item
Indent the file using the default indentation parameters.
......
......@@ -545,7 +545,7 @@ using the next face automatically.
*** New option `imenu-generic-skip-comments-and-strings'.
** Info
---
*** New face `info-index-match' is used to highlight matches in index
entries displayed by `Info-index-next', `Info-virtual-index' and
`info-apropos'.
......@@ -849,19 +849,23 @@ low-level libraries gfilenotify.c, inotify.c or w32notify.c.
* Incompatible Lisp Changes in Emacs 24.4
---
** `kill-region' lost its `yank-handler' optional argument.
+++
** `(input-pending-p)' no longer runs other timers which are ready to
run. The new optional CHECK-TIMERS param allows for the prior behavior.
** `defvar' and `defcustom' in a let-binding affect the "external" default.
---
** The syntax of ?» and ?« is now punctuation instead of matched parens.
Some languages match those as »...« and others as «...» so better stay neutral.
---
** In compiled Lisp files, the header no longer includes a timestamp.
+++
** The default file coding for Emacs Lisp files is now utf-8.
(See `file-coding-system-alist'.) In most cases, this change is
transparent, but files that contain unusual characters without
......@@ -869,6 +873,7 @@ specifying an explicit coding system may fail to load with obscure
errors. You should either convert them to utf-8 or add an explicit
`coding:' cookie.
+++
** `overriding-terminal-local-map' no longer replaces the local keymaps.
It used to disable the minor mode, major mode, and text-property keymaps,
whereas now it simply has higher precedence.
......@@ -881,9 +886,11 @@ Just as was the case in Emacs-22 and before, decoding of tty input according to
keyboard-coding-system is not performed in read-event any more. But contrary
to that past, it is still done before input-decode-map/function-key-map/...
** Removed inhibit-local-menu-bar-menus.
---
** Removed `inhibit-local-menu-bar-menus'.
** frame-local variables that affect redisplay do not work any more.
---
** Frame-local variables that affect redisplay do not work any more.
More specifically, the redisplay does not bother to check for a frame-local
value when looking up variables.
......
2013-12-25 Chong Yidong <cyd@gnu.org>
* keyboard.c (Voverriding_terminal_local_map):
(Voverriding_local_map): Doc fix.
* keymap.c (Vemulation_mode_map_alists): Doc fix.
2013-12-24 Eli Zaretskii <eliz@gnu.org>
* w32fns.c (Fw32_shell_execute): Ensure DOCUMENT is an absolute
......
......@@ -11415,18 +11415,19 @@ tool-bar separators natively. Otherwise it is unused (e.g. on GTK). */);
DEFVAR_KBOARD ("overriding-terminal-local-map",
Voverriding_terminal_local_map,
doc: /* Per-terminal keymap that takes precedence over all other keymaps.
This variable is intended to let commands such as `universal-argument'
set up a different keymap for reading the next command.
`overriding-terminal-local-map' has a separate binding for each
terminal device.
See Info node `(elisp)Multiple Terminals'. */);
terminal device. See Info node `(elisp)Multiple Terminals'. */);
DEFVAR_LISP ("overriding-local-map", Voverriding_local_map,
doc: /* Keymap that overrides almost all other local keymaps.
If this variable is non-nil, it is used as a keymap--replacing the
buffer's local map, the minor mode keymaps, and char property keymaps. */);
doc: /* Keymap that replaces (overrides) local keymaps.
If this variable is non-nil, Emacs looks up key bindings in this
keymap INSTEAD OF the keymap char property, minor mode maps, and the
buffer's local map. Hence, the only active keymaps would be
`overriding-terminal-local-map', this keymap, and `global-keymap', in
order of precedence. */);
Voverriding_local_map = Qnil;
DEFVAR_LISP ("overriding-local-map-menu-flag", Voverriding_local_map_menu_flag,
......
......@@ -3753,7 +3753,7 @@ it is provided for major modes to bind locally. */);
Vminor_mode_overriding_map_alist = Qnil;
DEFVAR_LISP ("emulation-mode-map-alists", Vemulation_mode_map_alists,
doc: /* List of keymap alists to use for emulations modes.
doc: /* List of keymap alists to use for emulation modes.
It is intended for modes or packages using multiple minor-mode keymaps.
Each element is a keymap alist just like `minor-mode-map-alist', or a
symbol with a variable binding which is a keymap alist, and it is used
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment