bug#33808:

[Spenser Truex]

Here I reproduce an email sent to emacs-devel@gnu.org and I suggest
edits to the eshell manual
https://www.gnu.org/software/emacs/manual/eshell.html which currently
lacks information on keybinding. This is unfortunate as eshell suffers
from a major bug related to keybinding.
>Hello,
>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. The following also runs without issue:
>M-x emacs-byte-compile-and-load ;in the new esh-mode.el buffer
>(require 'esh-mode)
>
>
>I am skeptical that any performance benefit here is worth breaking the 
>standard keybinding mechanism.

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. Use
>(add-hook 'eshell-mode-hook
>    (lambda ()
>        (define-key eshell-mode-map (kbd "key1") 'command1)
>         (define-key eshell-mode-map (kbd "key2") 'command2))
instead.