confusion on keymap's forms in doc

confusion on keymap's forms in doc

[Xah]

here's something unclear to me:

According to the manual
http://xahlee.org/elisp/Format-of-Keymaps.html

quote:
«
Each keymap is a list whose CAR is the symbol `keymap'.  The remaining
elements of the list define the key bindings of the keymap.

...

   Here as an example is the local keymap for Lisp mode, a sparse
keymap.  It defines bindings for <DEL> and <TAB>, plus `C-c C-l',
`M-C-q', and `M-C-x'.

     lisp-mode-map
     =>
     (keymap
      (3 keymap
         ;; C-c C-z
         (26 . run-lisp))
      (27 keymap
          ;; `M-C-x', treated as `<ESC> C-x'
          (24 . lisp-send-defun)
          keymap
          ;; `M-C-q', treated as `<ESC> C-q'
          (17 . indent-sexp))
      ;; This part is inherited from `lisp-mode-shared-map'.
      keymap
      ;; <DEL>
      (127 . backward-delete-char-untabify)
      (27 keymap
          ;; `M-C-q', treated as `<ESC> C-q'
          (17 . indent-sexp))
      (9 . lisp-indent-line))
»

if we look at the lisp-mode-map example above, it has 5 items. (not
counting the first item “keymap”, and the third item ‘keymap’ is
probably typo orphaned from above comment line”)

If we look at the item

(3 keymap
         ;; C-c C-z
         (26 . run-lisp))

this does not seem to be one of the form specified for allowed
elements in a keymap. The doc says the following form is allowed:

«
(type . binding)
(t . binding)
char-table
string
»

Should the doc add a form “(type . keymap)”?

also, in:
http://xahlee.org/elisp/Inheritance-and-Keymaps.html
it says:

«A keymap can inherit the bindings of another keymap, which we call
the parent keymap. Such a keymap looks like this:

     (keymap bindings... . parent-keymap)
»

if i understand it correctly, when expanded, such a keymap looks like
this:

(keymap
element-1
element-2
element-3
...
element-n
symbolOfParentKeymap
)

So, effectively, such a keymap is effectively having a
symbolOfParentKeymap appended to the original keymap list. Is that
right?

  Xah
∑ http://xahlee.org/

☄

Re: confusion on keymap's forms in doc

[Kevin Rodgers]

Xah wrote:
> here's something unclear to me:
> 
> According to the manual
> http://xahlee.org/elisp/Format-of-Keymaps.html
> 
> quote:
> «
> Each keymap is a list whose CAR is the symbol `keymap'.  The remaining
> elements of the list define the key bindings of the keymap.
> 
> ...
> 
>    Here as an example is the local keymap for Lisp mode, a sparse
> keymap.  It defines bindings for <DEL> and <TAB>, plus `C-c C-l',
> `M-C-q', and `M-C-x'.
> 
>      lisp-mode-map
>      =>
>      (keymap
>       (3 keymap
>          ;; C-c C-z
>          (26 . run-lisp))
>       (27 keymap
>           ;; `M-C-x', treated as `<ESC> C-x'
>           (24 . lisp-send-defun)
>           keymap
>           ;; `M-C-q', treated as `<ESC> C-q'
>           (17 . indent-sexp))
>       ;; This part is inherited from `lisp-mode-shared-map'.
>       keymap
>       ;; <DEL>
>       (127 . backward-delete-char-untabify)
>       (27 keymap
>           ;; `M-C-q', treated as `<ESC> C-q'
>           (17 . indent-sexp))
>       (9 . lisp-indent-line))
> »
> 
> if we look at the lisp-mode-map example above, it has 5 items. (not
> counting the first item “keymap”, and the third item ‘keymap’ is
> probably typo orphaned from above comment line”)

That keymap symbol is not a typo.  The actual underlying structure
is: (keymap (3 …) (27 …) . (keymap (127 …) (27 …) (9 …)))

Note the dot after the 3rd element, (27 …)

See the "Lists and Cons Cells" and "Dotted Pair Notation" nodes of the
Emacs Lisp manual.

> If we look at the item
> 
> (3 keymap
>          ;; C-c C-z
>          (26 . run-lisp))
> 
> this does not seem to be one of the form specified for allowed
> elements in a keymap. The doc says the following form is allowed:
> 
> «
> (type . binding)
> (t . binding)
> char-table
> string
> »
> 
> Should the doc add a form “(type . keymap)”?

Or change this:

`(TYPE . BINDING)'
      This specifies one binding, for events of type TYPE.  Each
      ordinary binding applies to events of a particular "event type",
      which is always a character or a symbol.  *Note Classifying
      Events::.  In this kind of binding, BINDING is a command.
                 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

to: In this kind of binding, BINDING is a command or a keymap.

See "Prefix Keys".

> also, in:
> http://xahlee.org/elisp/Inheritance-and-Keymaps.html
> it says:
> 
> «A keymap can inherit the bindings of another keymap, which we call
> the parent keymap. Such a keymap looks like this:
> 
>      (keymap bindings... . parent-keymap)
> »
> 
> if i understand it correctly, when expanded, such a keymap looks like
> this:
> 
> (keymap
> element-1
> element-2
> element-3
> ...
> element-n
> symbolOfParentKeymap
> )
> 
> So, effectively, such a keymap is effectively having a
> symbolOfParentKeymap appended to the original keymap list. Is that
> right?

I don't think so.  I think the actual keymap value of the symbol is
spliced into the inheriting keymap:

(keymap binding-1 binding-2 binding-3 … binding-n . (keymap …))

Note the warning a few paragraphs later:

    The proper way to construct a keymap with a parent is to use
`set-keymap-parent'; if you have code that directly constructs a keymap
with a parent, please convert the program to use `set-keymap-parent'
instead.

-- 
Kevin Rodgers
Denver, Colorado, USA