Patch to fix error in Emacs-Lisp Reference Manual

Patch to fix error in Emacs-Lisp Reference Manual

[Francis Litterio]

The "Active Keymaps" node in the Emacs-Lisp Reference Manual (in file
keymaps.texi) contradicts itself regarding the semantics of variable
overriding-local-map.  The below patch fixes this contradiction.
--
Francis Litterio
franl <at> world . std . com


--- keymaps.texi	10 Aug 2004 11:40:14 -0400	1.53
+++ keymaps.texi	12 Jan 2005 14:14:34 -0500	
@@ -566,7 +566,7 @@
 supply a binding for the key, Emacs searches the local map; if that too
 has no binding, Emacs then searches the global map.  However, if
 @code{overriding-local-map} is non-@code{nil}, Emacs searches that map
-first, before the global map.
+first, before the minor mode maps.
 
 @cindex major mode keymap
   Since every buffer that uses the same major mode normally uses the

Re: Patch to fix error in Emacs-Lisp Reference Manual

[Thien-Thi Nguyen]

   From: Francis Litterio <franl@world.std.com>
   Date: Wed, 12 Jan 2005 14:14:56 -0500

   The "Active Keymaps" node in the Emacs-Lisp Reference Manual (in file
   keymaps.texi) contradicts itself regarding the semantics of variable
   overriding-local-map.  The below patch fixes this contradiction.

thanks, installed.

please in the future include a ChangeLog entry, e.g.:

2005-01-13  Francis Litterio  <franl@world.std.com>  (tiny change)

	* keymaps.texi (Active Keymaps):
	Fix overriding-local-map description.

that will make things go smoother, especially for maintainers who might
not fully understand the changes in the patch.  the precise date is not
as important as the other info; it will get adjusted at commit-time.

thi

Re: Patch to fix error in Emacs-Lisp Reference Manual

[Luc Teirlinck]

 Francis Litterio wrote:

   --- keymaps.texi	10 Aug 2004 11:40:14 -0400	1.53
   +++ keymaps.texi	12 Jan 2005 14:14:34 -0500	
   @@ -566,7 +566,7 @@
    supply a binding for the key, Emacs searches the local map; if that too
    has no binding, Emacs then searches the global map.  However, if
    @code{overriding-local-map} is non-@code{nil}, Emacs searches that map
   -first, before the global map.
   +first, before the minor mode maps.

and Thien-Thi Nguyen wrote:

   thanks, installed.

Sorry, for not noticing this thread before.  This change is wrong.  A
little bit earlier in `(elisp)Active Keymaps' we see:

   The variable `overriding-local-map', if non-`nil', specifies
   another local keymap that overrides the buffer's local map and all
   the minor mode keymaps.

and a little bit later:

 -- Variable: overriding-local-map
     If non-`nil', this variable holds a keymap to use instead of the
     buffer's local keymap, text property or overlay keymaps, and
     instead of all the minor mode keymaps.  This keymap, if any,
     overrides all other maps that would have been active, except for
     the current global map.


In other words, `overriding-local-map' _overrides_ the minor mode
keymaps and the local map.  If it is non-nil, it is called before the
_global_ map, and _not_ before the minor mode maps, which are not
called at all.

The easiest fix would be to just revert the change.  Alternatively,
one could clarify the sentence, as in the patch below, even though it
gets rather repetitive, because exactly the same thing is already
pointed out a little bit earlier and a little bit later.

===File ~/keymaps.texi-diff=================================
*** keymaps.texi	13 Jan 2005 07:53:17 -0600	1.54
--- keymaps.texi	13 Jan 2005 08:33:29 -0600	
***************
*** 566,572 ****
  supply a binding for the key, Emacs searches the local map; if that too
  has no binding, Emacs then searches the global map.  However, if
  @code{overriding-local-map} is non-@code{nil}, Emacs searches that map
! first, before the minor mode maps.
  
  @cindex major mode keymap
    Since every buffer that uses the same major mode normally uses the
--- 566,573 ----
  supply a binding for the key, Emacs searches the local map; if that too
  has no binding, Emacs then searches the global map.  However, if
  @code{overriding-local-map} is non-@code{nil}, Emacs searches that map
! first, before the before the global map and ignores the minor mode
! maps and the local map.
  
  @cindex major mode keymap
    Since every buffer that uses the same major mode normally uses the
============================================================

Re: Patch to fix error in Emacs-Lisp Reference Manual

[Francis Litterio]

Luc Teirlinck wrote:

> In other words, `overriding-local-map' _overrides_ the minor mode
> keymaps and the local map.  If it is non-nil, it is called before the
> _global_ map, and _not_ before the minor mode maps, which are not
> called at all.

Yes.  Sorry.  That was my mistake.

> *** keymaps.texi	13 Jan 2005 07:53:17 -0600	1.54
> --- keymaps.texi	13 Jan 2005 08:33:29 -0600	
> ***************
> *** 566,572 ****
>   supply a binding for the key, Emacs searches the local map; if that too
>   has no binding, Emacs then searches the global map.  However, if
>   @code{overriding-local-map} is non-@code{nil}, Emacs searches that map
> ! first, before the minor mode maps.
>   
>   @cindex major mode keymap
>     Since every buffer that uses the same major mode normally uses the
> --- 566,573 ----
>   supply a binding for the key, Emacs searches the local map; if that too
>   has no binding, Emacs then searches the global map.  However, if
>   @code{overriding-local-map} is non-@code{nil}, Emacs searches that map
> ! first, before the before the global map and ignores the minor mode
> ! maps and the local map.
>   
>   @cindex major mode keymap
>     Since every buffer that uses the same major mode normally uses the

Does a non-nil overriding-local-map also override text property and
overlay keymaps?
--
Francis Litterio
franl <at> world . std . com

Re: Patch to fix error in Emacs-Lisp Reference Manual

[Luc Teirlinck]

Francis Litterio wrote:

   Does a non-nil overriding-local-map also override text property and
   overlay keymaps?

Yes, but those details are pointed out in the definition of
`overriding-local-map'.

Sincerely,

Luc.

Re: Patch to fix error in Emacs-Lisp Reference Manual

[Richard Stallman]

    The "Active Keymaps" node in the Emacs-Lisp Reference Manual (in file
    keymaps.texi) contradicts itself regarding the semantics of variable
    overriding-local-map.

A contradiction involves two statements that conflict.  I presume your
diff identifies one of the two statements.  Where is the other?

The statement you showed is correct--it fits what the code does.  The
changed version doesn't fit the code.

I will rewrite that node to try to make it clearer.

Re: Patch to fix error in Emacs-Lisp Reference Manual

[Richard Stallman]

I installed changes yesterday to clarify all these issues
in the manual.