bug#33808:

[Noam Postavsky <npostavs@gmail.com>]

On Wed, 19 Dec 2018 at 19:39, Spenser Truex <struex0@gmail.com> wrote:

> >It isn't possible to bind keys to eshell-mode-map using define-keys like this:
> >(define-key eshell-mode-map (kbd "<C-f12>") 'other-window)
> >instead a user must use an add-hook
> >(add-hook 'eshell-mode-hook (lambda () (define-key eshell-mode-map (kbd "<C-f12>") 'other-window)
> >The cause of this can be seen in the patch: eshell-mode-map is set to nil initially "for the byte compiler," then made buffer local (amusingly commented out with FIXME: What the hell?!). This patch resolves the issue and manages to byte compile.
> >
> >What is the benefit to setting it to nil initially with respect to the byte compiler? The comment above the defvar Also what is the benefit of setting it locally when it is already defined globally? The new version byte compiles okay, and the above test cases work.

It's not quite enough, because eshell-mode defines some more keys, so
settings like

(define-key eshell-command-map [(control ?a)] 'my-eshell-bol)

would still get overridden every time eshell starts. And there are
additional key definitions in other eshell files. The definitions set
up by eshell-command seem the most tricky to fix (probably requires
splitting out to a separate keymap):

    (defun eshell-return-exits-minibuffer ()
      (define-key eshell-mode-map [(control ?g)] 'abort-recursive-edit)
      (define-key eshell-mode-map [return] 'exit-minibuffer)
      ...)

    (defun eshell-command (&optional command arg)
       ...
        ;; Enable `eshell-mode' only in this minibuffer.
        (minibuffer-with-setup-hook #'(lambda ()
                                        (eshell-mode)
                                        (eshell-return-exits-minibuffer))


> And my recommended edit (to be put under the "5.4 Key rebinding" heading):
> Eshell currently suffers (version 27) from a bug concerning keybinding such that
> >(define-key eshell-mode-map (kbd "key") 'command)
> cannot be used before the hooks are run.

We don't document bugs in the manual.