bug#7803: 23.1; Need better definition of vector notation in define-key

bug#7803: 23.1; Need better definition of vector notation in define-key

[cppljevans]

  This is a documentation bug only.  I was trying to figure out how to
  specify either tab and shift-tab as the KEY argument to define-key.
  While in emacs, I entered commands:
  
    C-h i
    m Elisp
    i define-key
    
  this got me to an info node where the mode line contained:
  
    *info* (elisp) Changing Key Bindings 25% (48,0)   (Info Narrow)
    
  which contained:
  
 -- Function: define-key keymap key binding
     This function sets the binding for KEY in KEYMAP.  (If KEY is more
     than one event long, the change is actually made in another keymap
     reached from KEYMAP.)  The argument BINDING can be any Lisp
     object, but only certain types are meaningful.  (For a list of
     meaningful types, see *note Key Lookup::.)  The value returned by
     `define-key' is BINDING.

     If KEY is `[t]', this sets the default binding in KEYMAP.  When an
     event has no binding of its own, the Emacs command loop uses the
     keymap's default binding, if there is one.
  
  however, there's no explanation of what t in `[t]' can be.  Also,
  the phrase, 'default binding', implies there's a non-default
  binding.  IOW, there's more than one binding for a KEY, which is
  confusing to me because that implies a KEY is ambiguous,
  i.e. pressing KEY could mean either execute the default or
  non-default binding. A link to some explanation of 'default binding'
  would clarify.
  
  Elsewhere in the 'Changing Key Bindings' info node, there's this:
  
    In writing the key sequence to rebind, it is good to use the
    special escape sequences for control and meta characters (*note
    String Type::). The syntax `\C-' means that the following
    character is a control character and `\M-' means that the
    following character is a meta character.  Thus, the string
    `"\M-x"' is read as containing a single `M-x', `"\C-f"' is read as
    containing a single `C-f', and `"\M-\C-x"' and `"\C-\M-x"' are
    both read as containing a single `C-M-x'.  You can also use this
    escape syntax in vectors, as well as others that aren't allowed in
    strings; one example is `[?\C-\H-x home]'.  *Note Character
    Type::.
    
  However, there's no indication of what the code for shift is.  I
  could guess \S; however, that should be explicitly shown or a link
  provided which does show it.  Only by browsing around info could I
  find this:
  
    The Lisp syntax for the shift bit is `\S-'; thus, `?\C-\S-o' or
    `?\C-\S-O' represents the shifted-control-o character. 
    
  in the 'Other Char Bits' info node.
  


In GNU Emacs 23.1.1 (x86_64-pc-linux-gnu, GTK+ Version 2.20.0)
 of 2010-03-29 on yellow, modified by Debian
Windowing system distributor `The X.Org Foundation', version 11.0.10706000
configured using `configure  '--build=x86_64-linux-gnu' '--host=x86_64-linux-gnu' '--prefix=/usr' '--sharedstatedir=/var/lib' '--libexecdir=/usr/lib' '--localstatedir=/var/lib' '--infodir=/usr/share/info' '--mandir=/usr/share/man' '--with-pop=yes' '--enable-locallisppath=/etc/emacs23:/etc/emacs:/usr/local/share/emacs/23.1/site-lisp:/usr/local/share/emacs/site-lisp:/usr/share/emacs/23.1/site-lisp:/usr/share/emacs/site-lisp:/usr/share/emacs/23.1/leim' '--with-x=yes' '--with-x-toolkit=gtk' '--with-toolkit-scroll-bars' 'build_alias=x86_64-linux-gnu' 'host_alias=x86_64-linux-gnu' 'CFLAGS=-DDEBIAN -g -O2' 'LDFLAGS=-g' 'CPPFLAGS=''

Important settings:
  value of $LC_ALL: C
  value of $LC_COLLATE: nil
  value of $LC_CTYPE: nil
  value of $LC_MESSAGES: nil
  value of $LC_MONETARY: nil
  value of $LC_NUMERIC: nil
  value of $LC_TIME: nil
  value of $LANG: en_US.utf8
  value of $XMODIFIERS: nil
  locale-coding-system: nil
  default-enable-multibyte-characters: t

Major mode: Dired by name

Minor modes in effect:
  desktop-save-mode: t
  global-auto-revert-mode: t
  recentf-mode: t
  tooltip-mode: t
  tool-bar-mode: t
  mouse-wheel-mode: t
  menu-bar-mode: t
  file-name-shadow-mode: t
  global-font-lock-mode: t
  font-lock-mode: t
  blink-cursor-mode: t
  global-auto-composition-mode: t
  auto-composition-mode: t
  auto-encryption-mode: t
  auto-compression-mode: t
  column-number-mode: t
  line-number-mode: t
  transient-mark-mode: t

Recent input:
<help-echo> <help-echo> <help-echo> <help-echo> <help-echo> 
<help-echo> <help-echo> <help-echo> <help-echo> <help-echo> 
<help-echo> <menu-bar> <tools> <compose-mail> <help-echo> 
C-x 2 <menu-bar> <buffer> C-a e <help-echo> <down-mouse-1> 
<mouse-movement> <mouse-movement> <drag-mouse-1> <help-echo> 
<help-echo> <help-echo> <help-echo> <help-echo> <menu-bar> 
<edit> <copy> <down-mouse-1> <mouse-1> <help-echo> 
<help-echo> <help-echo> <help-echo> <help-echo> <help-echo> 
<menu-bar> <edit> <paste> <help-echo> <down-mouse-1> 
<mouse-movement> <mouse-movement> <drag-mouse-1> <help-echo> 
<help-echo> <help-echo> <help-echo> <help-echo> <help-echo> 
<help-echo> <menu-bar> <edit> <copy> <help-echo> <down-mouse-1> 
<mouse-1> <help-echo> <help-echo> <help-echo> <help-echo> 
<help-echo> <help-echo> <help-echo> <menu-bar> <edit> 
<paste> <help-echo> <down-mouse-1> <mouse-1> <down-mouse-1> 
<mouse-1> <down-mouse-1> <mouse-1> <down-mouse-1> <mouse-movement> 
<mouse-movement> <mouse-movement> <mouse-movement> 
<drag-mouse-1> <help-echo> <down-mouse-1> <mouse-1> 
C-@ <escape> > C-p C-p C-p C-p C-p C-p C-p C-p C-p 
C-p C-p C-p C-p C-p C-p C-p C-p C-p C-p C-p C-p C-p 
C-p C-p C-p C-p C-p C-p C-p C-p C-p C-p C-p C-p C-p 
C-p C-p C-p C-p C-p C-p C-p C-p C-p C-p C-p C-p C-p 
C-p C-p C-p C-p C-p C-p C-p C-p C-p C-p C-p C-p C-p 
C-p C-p C-p C-p C-p C-p C-p C-p C-p C-p C-p C-p C-p 
C-p C-p C-p C-p C-p C-p C-p C-p C-p C-p C-p C-p C-p 
C-n C-n C-n C-n C-n C-n C-n C-n C-n C-n <down-mouse-1> 
<mouse-1> <help-echo> <down-mouse-1> <mouse-1> <help-echo> 
<help-echo> <help-echo> <menu-bar> <mail> <cancel> 
<help-echo> <help-echo> <down-mouse-1> <mouse-1> <escape> 
x r e p o r t - e m <tab> <return>

Recent messages:
uncompressing emacs-7.gz...done
uncompressing emacs-8.gz...done
Wrote /home/evansl/.emacs.desktop.lock
Desktop: 10 buffers restored, 1 failed to restore.
c-tab-stop-my-list message
For information about GNU Emacs and the GNU system, type C-h C-a.
Startup with window [1]
c-tab-stop-my-list message
Mark set [3 times]
Auto-saving...done

bug#7803: 23.1; Need better definition of vector notation in define-key

[Andreas Schwab]

<cppljevans@suddenlink.net> writes:

>   however, there's no explanation of what t in `[t]' can be.

It is the symbol `t'.

>   Also, the phrase, 'default binding', implies there's a non-default
>   binding.

The term `default binding' is explained in the same paragraph.

Andreas.

-- 
Andreas Schwab, schwab@linux-m68k.org
GPG Key fingerprint = 58CA 54C7 6D53 942B 1756  01D3 44D5 214B 8276 4ED5
"And now for something completely different."

bug#7803: 23.1; Need better definition of vector notation in define-key

[Larry Evans]

On 01/07/11 17:09, Andreas Schwab wrote:
> <cppljevans@suddenlink.net> writes:
> 
>>   however, there's no explanation of what t in `[t]' can be.
> 
> It is the symbol `t'.
> 
>>   Also, the phrase, 'default binding', implies there's a non-default
>>   binding.
> 
> The term `default binding' is explained in the same paragraph.
> 
Ah, so when it says:

  If KEY is `[t]', this sets the default binding in KEYMAP.

it means:

  If the call to define-key is of the form:

     (define-key KEYMAP [T] BINDING)

  then this sets the default binding in KEYMAP to BINDING.

which, I guess means when the KEY argument is *not* in the form of
a vector, then it sets the non-default binding.  OOPS, wait, that
doesn't make sense to me eithe because a default and non-default
bindings would mean pressing KEY or the event represented by KEY
has at least 2 meansing.

So, the paragraph is still unclear to me.

What am I missing?

  -Larry

bug#7803: 23.1; Need better definition of vector notation in define-key

[Glenn Morris]

Larry Evans wrote:

> Ah, so when it says:
>
>   If KEY is `[t]', this sets the default binding in KEYMAP.
>
> it means:

You're overthinking it. It means literally what it says: a vector with
a single element `t'. Not a vector with any other contents.
`t' in Emacs documentation always means the special symbol `t', for truth.

Rather than reading the Lispref, the Emacs manual offers a better
introduction to key bindings for the purposes of user customization.

(I admit I couldn't see a clear mention of "S-" = "shift" there, though.)

bug#7803: 23.1; Need better definition of vector notation in define-key

[Larry Evans]

On 01/07/11 19:50, Glenn Morris wrote:
> Larry Evans wrote:
> 
>> Ah, so when it says:
>>
>>   If KEY is `[t]', this sets the default binding in KEYMAP.
>>
>> it means:
> 
> You're overthinking it. It means literally what it says: a vector with
> a single element `t'. Not a vector with any other contents.
> `t' in Emacs documentation always means the special symbol `t', for truth.

Ah. OK.  So if the KEY in

  (define-key KEYMAP KEY BINDING)

is `[t]', then BINDING is ignored, and, I guess, the default binding for
*all* keys in KEYMAP are set to the default binding?  I guess the
"default binding" is self-insert, IOW.

OOPS, now.  I finally went to help, entered define-key, and got:

> define-key is a built-in function in `C source code'.
> 
> (define-key keymap key def)
> 
> In keymap, define key sequence key as def.
> keymap is a keymap.
> 
> key is a string or a vector of symbols and characters meaning a
> sequence of keystrokes and events.  Non-ASCII characters with codes
> above 127 (such as ISO Latin-1) can be included if you use a vector.
> Using [t] for key creates a default definition, which applies to any
> event type that has no other definition in this keymap.

which finally cleared things up.  This tells me that after:

  (define KEYMAP [t] DEFAULT_BINDING)

then any key, KEY, which has *not* occurred in a call:

  (define-key KEYMAP KEY def)

for some value of def, has the DEFAULT_BINDING in KEYMAP.

Is that right?

> 
> Rather than reading the Lispref, the Emacs manual offers a better
> introduction to key bindings for the purposes of user customization.
> 
> (I admit I couldn't see a clear mention of "S-" = "shift" there, though.)
> 

After fishing around the manual, I found it in the info node, "Other
Char Bits" which contains:

  The Lisp syntax for the shift bit is `\S-'; thus, `?\C-\S-o' or
  `?\C-\S-O' represents the shifted-control-o character.

The ? was a bit  mysterious at first, but more fishing showed
me what it meant, but I don't remember where that info node is.

bug#7803: 23.1; Need better definition of vector notation in define-key

[Glenn Morris]

Larry Evans wrote:

>   (define KEYMAP [t] DEFAULT_BINDING)
>
> then any key, KEY, which has *not* occurred in a call:
>
>   (define-key KEYMAP KEY def)
>
> for some value of def, has the DEFAULT_BINDING in KEYMAP.

Yes.

> After fishing around the manual, I found it in the info node, "Other
> Char Bits" which contains:
>
>   The Lisp syntax for the shift bit is `\S-'; thus, `?\C-\S-o' or
>   `?\C-\S-O' represents the shifted-control-o character.
>
> The ? was a bit  mysterious at first, but more fishing showed
> me what it meant, but I don't remember where that info node is.

If you read the "Key Bindings" section in the Emacs manual (which
again, I think provides a better first introduction than the Elisp
manual), it gives clear examples of the vector syntax ("Rebinding Keys
in Your Init File"). It has C- and M-, it just doesn't mention S-,
AFAICS. C- and M- are explained right at the start of the manual
("2 Kinds of User Input").