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