magit-define-global-key-bindings: Improve documentation

Closes #4446.

3 files changed, 31 insertions, 13 deletions

diff --git a/Documentation/magit.org b/Documentation/magit.org
index f68bcd3..ef30e1a 100644
--- a/Documentation/magit.org
+++ b/Documentation/magit.org
@@ -8,7 +8,7 @@
 #+TEXINFO_DIR_CATEGORY: Emacs
 #+TEXINFO_DIR_TITLE: Magit: (magit).
 #+TEXINFO_DIR_DESC: Using Git from Emacs with Magit.
-#+SUBTITLE: for version 3.1.1 (v3.1.1-54-gd5ce70d3b+1)
+#+SUBTITLE: for version 3.1.1 (v3.1.1-55-gda5ac05e0+1)
 
 #+TEXINFO_DEFFN: t
 #+OPTIONS: H:4 num:3 toc:2
@@ -25,7 +25,7 @@ directly from within Emacs.  While many fine Git clients exist, only
 Magit and Git itself deserve to be called porcelains.
 
 #+TEXINFO: @noindent
-This manual is for Magit version 3.1.1 (v3.1.1-54-gd5ce70d3b+1).
+This manual is for Magit version 3.1.1 (v3.1.1-55-gda5ac05e0+1).
 
 #+BEGIN_QUOTE
 Copyright (C) 2015-2021 Jonas Bernoulli <jonas@bernoul.li>
@@ -7695,7 +7695,7 @@ for more information.
   | ~C-x M-g~ | ~magit-dispatch~      |
   | ~C-c M-g~ | ~magit-file-dispatch~ |
 
-  These bindings may be added when ~after-init-hook~ is called.
+  These bindings may be added when ~after-init-hook~ is run.
   Each binding is added if and only if at that time no other key
   is bound to the same command and no other command is bound to
   the same key.  In other words we try to avoid adding bindings
@@ -7709,8 +7709,14 @@ for more information.
   all the potentially conflicting user bindings have already
   been added.
 
-  Setting this variable after the hook has already been called
-  has no effect.
+  To set this variable use either ~setq~ or the Custom interface.
+  Do not use the function ~customize-set-variable~ because doing
+  that would cause Magit to be loaded immediately when that form
+  is evaluated (this differs from ~custom-set-variables~, which
+  doesn't load the libraries that define the customized variables).
+
+  Setting this variable to nil has no effect if that is done after
+  the key bindings have already been added.
 
   We recommend that you bind ~C-c g~ instead of ~C-c M-g~ to
   ~magit-file-dispatch~.  The former is a much better binding
diff --git a/Documentation/magit.texi b/Documentation/magit.texi
index 0534677..8c7f706 100644
--- a/Documentation/magit.texi
+++ b/Documentation/magit.texi
@@ -31,7 +31,7 @@ General Public License for more details.
 @finalout
 @titlepage
 @title Magit User Manual
-@subtitle for version 3.1.1 (v3.1.1-54-gd5ce70d3b+1)
+@subtitle for version 3.1.1 (v3.1.1-55-gda5ac05e0+1)
 @author Jonas Bernoulli
 @page
 @vskip 0pt plus 1filll
@@ -53,7 +53,7 @@ directly from within Emacs.  While many fine Git clients exist, only
 Magit and Git itself deserve to be called porcelains.
 
 @noindent
-This manual is for Magit version 3.1.1 (v3.1.1-54-gd5ce70d3b+1).
+This manual is for Magit version 3.1.1 (v3.1.1-55-gda5ac05e0+1).
 
 @quotation
 Copyright (C) 2015-2021 Jonas Bernoulli <jonas@@bernoul.li>
@@ -10379,7 +10379,7 @@ following bindings may be added to the global keymap.
 @tab @code{magit-file-dispatch}
 @end multitable
 
-These bindings may be added when @code{after-init-hook} is called.
+These bindings may be added when @code{after-init-hook} is run.
 Each binding is added if and only if at that time no other key
 is bound to the same command and no other command is bound to
 the same key.  In other words we try to avoid adding bindings
@@ -10393,8 +10393,14 @@ is loaded or autoloaded) and to increase the likelihood that
 all the potentially conflicting user bindings have already
 been added.
 
-Setting this variable after the hook has already been called
-has no effect.
+To set this variable use either @code{setq} or the Custom interface.
+Do not use the function @code{customize-set-variable} because doing
+that would cause Magit to be loaded immediately when that form
+is evaluated (this differs from @code{custom-set-variables}, which
+doesn't load the libraries that define the customized variables).
+
+Setting this variable to nil has no effect if that is done after
+the key bindings have already been added.
 
 We recommend that you bind @code{C-c g} instead of @code{C-c M-g} to
 @code{magit-file-dispatch}.  The former is a much better binding
diff --git a/lisp/magit.el b/lisp/magit.el
index 5e6683e..c58e490 100644
--- a/lisp/magit.el
+++ b/lisp/magit.el
@@ -237,7 +237,7 @@ C-x g           magit-status
 C-x M-g         magit-dispatch
 C-c M-g         magit-file-dispatch
 
-These bindings may be added when `after-init-hook' is called.
+These bindings may be added when `after-init-hook' is run.
 Each binding is added if and only if at that time no other key
 is bound to the same command and no other command is bound to
 the same key.  In other words we try to avoid adding bindings
@@ -251,8 +251,14 @@ is loaded or autoloaded) and to increase the likelihood that
 all the potentially conflicting user bindings have already
 been added.
 
-Setting this variable after the hook has already been called
-has no effect.
+To set this variable use either `setq' or the Custom interface.
+Do not use the function `customize-set-variable' because doing
+that would cause Magit to be loaded immediately when that form
+is evaluated (this differs from `custom-set-variables', which
+doesn't load the libraries that define the customized variables).
+
+Setting this variable to nil has no effect if that is done after
+the key bindings have already been added.
 
 We recommend that you bind \"C-c g\" instead of \"C-c M-g\" to
 `magit-file-dispatch'.  The former is a much better binding