Revision: emacs@sv.gnu.org/emacs--unicode--0--patch-11

Merge from emacs--devo--0

Patches applied:

 * emacs--devo--0  (patch 34-42)

   - Update from CVS
   - Merge from gnus--rel--5.10

 * gnus--rel--5.10  (patch 14-17)

   - Update from CVS
   - Merge from emacs--devo--0

3 files changed, 156 insertions, 49 deletions

diff --git a/lispref/frames.texi b/lispref/frames.texi
index 4b967d8989c..8212e9325f9 100644
--- a/lispref/frames.texi
+++ b/lispref/frames.texi
@@ -64,6 +64,7 @@ The frame is displayed on an MS-DOS terminal.
 * Dialog Boxes::                Displaying a box to ask yes or no.
 * Pointer Shapes::              Specifying the shape of the mouse pointer.
 * Window System Selections::    Transferring text to and from other X clients.
+* Drag and Drop::               Internals of Drag-and-Drop implementation.
 * Color Names::                 Getting the definitions of color names.
 * Text Terminal Colors::        Defining colors for text-only terminals.
 * Resources::                   Getting resource values from the server.
@@ -469,7 +470,7 @@ frame, or control their sizes.
 The width in pixels of the frame's border.
 
 @item internal-border-width
-The distance in pixels between text and the frame's border.
+The distance in pixels between text (or fringe) and the frame's border.
 
 @item vertical-scroll-bars
 Whether the frame has scroll bars for vertical scrolling, and which side
@@ -1685,6 +1686,35 @@ access the clipboard at all.  The default is @code{nil} on most systems,
 but @code{t} on MS-Windows.
 @end defopt
 
+@node Drag and Drop
+@section Drag and Drop
+
+@vindex x-dnd-test-function
+@vindex x-dnd-known-types
+  When a user drags something from another application over Emacs, that other
+application expects Emacs to tell it if Emacs can handle the data that is
+dragged.  The variable @code{x-dnd-test-function} is used by Emacs to determine
+what to reply.  The default value is @code{x-dnd-default-test-function}
+which accepts drops if the type of the data to be dropped is present in
+@code{x-dnd-known-types}.  You can customize @code{x-dnd-test-function} and/or
+@code{x-dnd-known-types} if you want Emacs to accept or reject drops based
+on some other criteria.
+
+@vindex x-dnd-types-alist
+  If you want to change the way Emacs handles drop of different types
+or add a new type, customize @code{x-dnd-types-alist}.  This requires
+detailed knowledge of what types other applications use for drag and
+drop.
+
+@vindex dnd-protocol-alist
+  When an URL is dropped on Emacs it may be a file, but it may also be
+another URL type (ftp, http, etc.).  Emacs first checks
+@code{dnd-protocol-alist} to determine what to do with the URL.  If
+there is no match there and if @code{browse-url-browser-function} is
+an alist, Emacs looks for a match there.  If no match is found the
+text for the URL is inserted.  If you want to alter Emacs behavior,
+you can customize these variables.
+
 @node Color Names
 @section Color Names
 
diff --git a/lispref/keymaps.texi b/lispref/keymaps.texi
index f30fb5c9659..5a732af4ebb 100644
--- a/lispref/keymaps.texi
+++ b/lispref/keymaps.texi
@@ -22,10 +22,13 @@ found.  The whole process is called @dfn{key lookup}.
 * Inheritance and Keymaps::     How one keymap can inherit the bindings
                                    of another keymap.
 * Prefix Keys::                 Defining a key with a keymap as its definition.
-* Active Keymaps::              Each buffer has a local keymap
+* Active Keymaps::              How Emacs searches the active keymaps
+                                   for a key binding.
+* Searching Keymaps::           A pseudo-Lisp summary of searching active maps.
+* Controlling Active Maps::     Each buffer has a local keymap
                                    to override the standard (global) bindings.
                                    A minor mode can also override them.
-* Key Lookup::                  How extracting elements from keymaps works.
+* Key Lookup::                  Finding a key's binding in one keymap.
 * Functions for Key Lookup::    How to request key lookup.
 * Changing Key Bindings::       Redefining a key in a keymap.
 * Remapping Commands::          Bindings that translate one command to another.
@@ -537,17 +540,38 @@ string for the keymap.  The prompt string should be given for menu keymaps
 @cindex local keymap
 
   Emacs normally contains many keymaps; at any given time, just a few
-of them are @dfn{active} in that they participate in the
+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.
 Emacs searches these keymaps one by one, in a standard order, until it
-finds a binding in one of the keymaps.  (Searching a single keymap for a
-binding is called @dfn{key lookup}; see @ref{Key Lookup}.)
+finds a binding in one of the keymaps.
 
   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.  Therefore, Emacs
-searches for each input key sequence in all these keymaps.
+searches for each input key sequence in all these keymaps.  Here is a
+pseudo-Lisp description of how this process works:
+
+@lisp
+(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-text-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-text-property (point) 'local-map))
+              (@var{find-in} (current-local-map))))))
+    (@var{find-in} (current-global-map)))
+@end lisp
+
+@noindent
+Here, the pseudo-function @var{find-in} means to look up the key
+sequence in a single map, and @var{find-in-any} means to search the
+appropriate keymaps from an alist.  (Searching a single keymap for a
+binding is called @dfn{key lookup}; see @ref{Key Lookup}.)
 
   The @dfn{global keymap} holds the bindings of keys that are defined
 regardless of the current buffer, such as @kbd{C-f}.  The variable
@@ -597,10 +621,92 @@ events within @code{read-key-sequence}.  @xref{Translating Input}.
 
   @xref{Standard Keymaps}, for a list of standard keymaps.
 
+@defun current-active-maps &optional olp
+This returns the list of active keymaps that would be used by the
+command loop in the current circumstances to look up a key sequence.
+Normally it ignores @code{overriding-local-map} and
+@code{overriding-terminal-local-map}, but if @var{olp} is
+non-@code{nil} then it pays attention to them.
+@end defun
+
+@defun key-binding key &optional accept-defaults no-remap
+This function returns the binding for @var{key} according to the
+current active keymaps.  The result is @code{nil} if @var{key} is
+undefined in the keymaps.
+
+@c Emacs 19 feature
+The argument @var{accept-defaults} controls checking for default
+bindings, as in @code{lookup-key} (above).
+
+When commands are remapped (@pxref{Remapping Commands}),
+@code{key-binding} normally processes command remappings so as to
+returns the remapped command that will actually be executed.  However,
+if @var{no-remap} is non-@code{nil}, @code{key-binding} ignores
+remappings and returns the binding directly specified for @var{key}.
+
+An error is signaled if @var{key} is not a string or a vector.
+
+@example
+@group
+(key-binding "\C-x\C-f")
+    @result{} find-file
+@end group
+@end example
+@end defun
+
+@node Searching Keymaps
+@section Searching the Active Keymaps
+
+  After translation of the input events (@pxref{Translating Input})
+Emacs looks for them in the active keymaps.  Here is a pseudo-Lisp
+description of the order in which the active keymaps are searched:
+
+@lisp
+(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-text-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)
+            (@var{find-in} (get-text-property (point) 'local-map))
+            (@var{find-in} (current-local-map)))))
+    (@var{find-in} (current-global-map)))
+@end lisp
+
+@noindent
+The @var{find-in} and @var{find-in-any} are pseudo functions that
+searches in one keymap respectively an alist of keymaps.
+
+@enumerate
+@item
+The function finally found may be remapped
+(@pxref{Remapping Commands}).
+
+@item
+Characters that are bound to @code{self-insert-command} are translated
+according to @code{translation-table-for-input} before insertion.
+
+@item
+@code{current-active-maps} returns a list of the
+currently active keymaps at point.
+
+@item
+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.
+@end enumerate
+
+@node Controlling Active Maps
+@section Controlling the Active Keymaps
+
 @defvar global-map
 This variable contains the default global keymap that maps Emacs
-keyboard input to commands.  The global keymap is normally this keymap.
-The default global keymap is a full keymap that binds
+keyboard input to commands.  The global keymap is normally this
+keymap.  The default global keymap is a full keymap that binds
 @code{self-insert-command} to all of the printing characters.
 
 It is normal practice to change the bindings in the global keymap, but you
@@ -763,14 +869,14 @@ are used before @code{minor-mode-map-alist} and
 @cindex keymap entry
 
   @dfn{Key lookup} is the process of finding the binding of a key
-sequence from a given keymap.  Actual execution of the binding is not
-part of key lookup.
+sequence from a given keymap.  The execution or use of the binding is
+not part of key lookup.
 
   Key lookup uses just the event type of each event in the key sequence;
 the rest of the event is ignored.  In fact, a key sequence used for key
 lookup may designate a mouse event with just its types (a symbol)
 instead of the entire event (a list).  @xref{Input Events}.  Such
-a ``key-sequence'' is insufficient for @code{command-execute} to run,
+a ``key sequence'' is insufficient for @code{command-execute} to run,
 but it is sufficient for looking up or rebinding a key.
 
   When the key sequence consists of multiple events, key lookup
@@ -965,39 +1071,6 @@ Used in keymaps to undefine keys.  It calls @code{ding}, but does
 not cause an error.
 @end deffn
 
-@defun key-binding key &optional accept-defaults no-remap
-This function returns the binding for @var{key} in the current
-keymaps, trying all the active keymaps.  The result is @code{nil} if
-@var{key} is undefined in the keymaps.
-
-@c Emacs 19 feature
-The argument @var{accept-defaults} controls checking for default
-bindings, as in @code{lookup-key} (above).
-
-When commands are remapped (@pxref{Remapping Commands}),
-@code{key-binding} normally processes command remappings so as to
-returns the remapped command that will actually be executed.  However,
-if @var{no-remap} is non-@code{nil}, @code{key-binding} ignores
-remappings and returns the binding directly specified for @var{key}.
-
-An error is signaled if @var{key} is not a string or a vector.
-
-@example
-@group
-(key-binding "\C-x\C-f")
-    @result{} find-file
-@end group
-@end example
-@end defun
-
-@defun current-active-maps &optional olp
-This returns the list of keymaps that would be used by the command
-loop in the current circumstances to look up a key sequence.  Normally
-it ignores @code{overriding-local-map} and
-@code{overriding-terminal-local-map}, but if @var{olp} is
-non-@code{nil} then it pays attention to them.
-@end defun
-
 @defun local-key-binding key &optional accept-defaults
 This function returns the binding for @var{key} in the current
 local keymap, or @code{nil} if it is undefined there.
@@ -1036,11 +1109,11 @@ bindings, as in @code{lookup-key} (above).
 
 @defvar meta-prefix-char
 @cindex @key{ESC}
-This variable is the meta-prefix character code.  It is used when
+This variable is the meta-prefix character code.  It is used for
 translating a meta character to a two-character sequence so it can be
-looked up in a keymap.  For useful results, the value should be a prefix
-event (@pxref{Prefix Keys}).  The default value is 27, which is the
-@acronym{ASCII} code for @key{ESC}.
+looked up in a keymap.  For useful results, the value should be a
+prefix event (@pxref{Prefix Keys}).  The default value is 27, which is
+the @acronym{ASCII} code for @key{ESC}.
 
 As long as the value of @code{meta-prefix-char} remains 27, key lookup
 translates @kbd{M-b} into @kbd{@key{ESC} b}, which is normally defined
diff --git a/lispref/minibuf.texi b/lispref/minibuf.texi
index 6f98785f69f..c0990bae3ee 100644
--- a/lispref/minibuf.texi
+++ b/lispref/minibuf.texi
@@ -583,6 +583,10 @@ themselves to do with minibuffers.  We describe them in this chapter
 so as to keep them near the higher-level completion features that do
 use the minibuffer.
 
+  If you store a completion alist in a variable, you should mark the
+variable as ``risky'' with a non-@code{nil}
+@code{risky-local-variable} property.
+
 @defun try-completion string collection &optional predicate
 This function returns the longest common substring of all possible
 completions of @var{string} in @var{collection}.  The value of