bug#33808:

[Spenser Truex <struex0@gmail.com>]

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.