From c93525876d67837669c5e8f89b6606b4cfb55ec4 Mon Sep 17 00:00:00 2001 From: Chong Yidong Date: Wed, 25 Dec 2013 18:24:52 +0800 Subject: [PATCH] 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. --- doc/emacs/ChangeLog | 4 + doc/emacs/glossary.texi | 12 ++- doc/emacs/mule.texi | 1 - doc/lispref/ChangeLog | 20 ++++ doc/lispref/commands.texi | 6 +- doc/lispref/display.texi | 4 +- doc/lispref/keymaps.texi | 196 ++++++++++++++++++-------------------- doc/lispref/nonascii.texi | 16 ++-- doc/lispref/tips.texi | 13 +-- etc/NEWS | 13 ++- src/ChangeLog | 7 ++ src/keyboard.c | 13 +-- src/keymap.c | 2 +- 13 files changed, 171 insertions(+), 136 deletions(-) diff --git a/doc/emacs/ChangeLog b/doc/emacs/ChangeLog index 9b6868857e..96008f63e9 100644 --- a/doc/emacs/ChangeLog +++ b/doc/emacs/ChangeLog @@ -1,3 +1,7 @@ +2013-12-25 Chong Yidong + + * glossary.texi (Glossary): Define MULE in modern terms. + 2013-12-25 Xue Fuqiao * files.texi (Diff Mode): Add an index. diff --git a/doc/emacs/glossary.texi b/doc/emacs/glossary.texi index c8b4b40416..d6c8477b1c 100644 --- a/doc/emacs/glossary.texi +++ b/doc/emacs/glossary.texi @@ -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 diff --git a/doc/emacs/mule.texi b/doc/emacs/mule.texi index 6efbc2b719..e0653c96f8 100644 --- a/doc/emacs/mule.texi +++ b/doc/emacs/mule.texi @@ -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 diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog index 738dd417fd..354efd5f40 100644 --- a/doc/lispref/ChangeLog +++ b/doc/lispref/ChangeLog @@ -1,3 +1,23 @@ +2013-12-25 Chong Yidong + + * 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 * control.texi (Pattern matching case statement): Rephrase lexical diff --git a/doc/lispref/commands.texi b/doc/lispref/commands.texi index 846d6f3a4a..a932264088 100644 --- a/doc/lispref/commands.texi +++ b/doc/lispref/commands.texi @@ -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 diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi index ead436ab80..6bb8f64d9e 100644 --- a/doc/lispref/display.texi +++ b/doc/lispref/display.texi @@ -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 diff --git a/doc/lispref/keymaps.texi b/doc/lispref/keymaps.texi index 86e205cf14..c5ffbc964c 100644 --- a/doc/lispref/keymaps.texi +++ b/doc/lispref/keymaps.texi @@ -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 diff --git a/doc/lispref/nonascii.texi b/doc/lispref/nonascii.texi index ddbb5aeaa6..7b499159d9 100644 --- a/doc/lispref/nonascii.texi +++ b/doc/lispref/nonascii.texi @@ -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 diff --git a/doc/lispref/tips.texi b/doc/lispref/tips.texi index 26d81f738f..159938eedf 100644 --- a/doc/lispref/tips.texi +++ b/doc/lispref/tips.texi @@ -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. diff --git a/etc/NEWS b/etc/NEWS index 00a72f03e0..de461aa2bf 100644 --- a/etc/NEWS +++ b/etc/NEWS @@ -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. diff --git a/src/ChangeLog b/src/ChangeLog index 1de6122edd..a883182754 100644 --- a/src/ChangeLog +++ b/src/ChangeLog @@ -1,3 +1,10 @@ +2013-12-25 Chong Yidong + + * keyboard.c (Voverriding_terminal_local_map): + (Voverriding_local_map): Doc fix. + + * keymap.c (Vemulation_mode_map_alists): Doc fix. + 2013-12-24 Eli Zaretskii * w32fns.c (Fw32_shell_execute): Ensure DOCUMENT is an absolute diff --git a/src/keyboard.c b/src/keyboard.c index 915ce9dcf2..8ccbf77871 100644 --- a/src/keyboard.c +++ b/src/keyboard.c @@ -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, diff --git a/src/keymap.c b/src/keymap.c index 562787ee8a..9ef5a0b294 100644 --- a/src/keymap.c +++ b/src/keymap.c @@ -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 -- 2.20.1