magit-toggle-git-debug: Improve documentation

Focus on documenting the command `magit-toggle-git-debug', at the
expense of the documentation for the variable `magit-git-debug',
which users don't really have to know about.

2 files changed, 50 insertions, 68 deletions

diff --git a/docs/magit.org b/docs/magit.org
index 72a4cac..0388715 100644
--- a/docs/magit.org
+++ b/docs/magit.org
@@ -1840,10 +1840,9 @@ sections are available.  There is one additional command.
 
   This command kills the process represented by the section at point.
 
-- Variable: magit-git-debug ::
+- Key: M-x magit-toggle-git-debug ::
 
-  This option controls whether additional reporting of git errors is
-  enabled.
+  This command toggles whether additional git errors are reported.
 
   Magit basically calls git for one of these two reasons: for
   side-effects or to do something with its standard output.
@@ -1852,24 +1851,17 @@ sections are available.  There is one additional command.
   messages, go into the process buffer which is shown when using ~$~.
 
   When git's output is consumed in some way, then it would be too
-  expensive to also insert it into this buffer, but when this
-  option is non-nil and git returns with a non-zero exit status,
-  then at least its standard error is inserted into this buffer.
-
-  This is only intended for debugging purposes.  Do not enable this
-  permanently, that would negatively affect performance.
-
-  This is only intended for debugging purposes.  Do not enable this
-  permanently, that would negatively affect performance.  Also note
-  that just because git exits with a non-zero exit status and prints
-  an error message that usually doesn't mean that it is an error as
-  far as Magit is concerned, which is another reason we usually hide
-  these error messages.  Whether some error message is relevant in
-  the context of some unexpected behavior has to be judged on a case
-  by case basis.
-
-  The command ~magit-toggle-git-debug~ changes the value of this
-  variable.
+  expensive to also insert it into this buffer, but with this command
+  that can be enabled temporarily.  In that case, if git returns with
+  a non-zero exit status, then at least its standard error is inserted
+  into this buffer.
+
+  Also note that just because git exits with a non-zero status and
+  prints an error message, that usually doesn't mean that it is an
+  error as far as Magit is concerned, which is another reason we
+  usually hide these error messages.  Whether some error message is
+  relevant in the context of some unexpected behavior has to be judged
+  on a case by case basis.
 
 - Variable: magit-process-extreme-logging ::
 
@@ -9338,18 +9330,17 @@ issue.
   messages, go into the process buffer which is shown when using ~$~.
 
   When git's output is consumed in some way, then it would be too
-  expensive to also insert it into this buffer, but when this
-  option is non-nil and git returns with a non-zero exit status,
-  then at least its standard error is inserted into this buffer.
-
-  This is only intended for debugging purposes.  Do not enable this
-  permanently, that would negatively affect performance.  Also note
-  that just because git exits with a non-zero exit status and prints
-  an error message that usually doesn't mean that it is an error as
-  far as Magit is concerned, which is another reason we usually hide
-  these error messages.  Whether some error message is relevant in
-  the context of some unexpected behavior has to be judged on a case
-  by case basis.
+  expensive to also insert it into this buffer, but with this command
+  that can be enabled temporarily.  In that case, if git returns with
+  a non-zero exit status, then at least its standard error is inserted
+  into this buffer.
+
+  Also note that just because git exits with a non-zero status and
+  prints an error message, that usually doesn't mean that it is an
+  error as far as Magit is concerned, which is another reason we
+  usually hide these error messages.  Whether some error message is
+  relevant in the context of some unexpected behavior has to be judged
+  on a case by case basis.
 
 - Key: M-x magit-toggle-verbose-refresh ::
 
diff --git a/docs/magit.texi b/docs/magit.texi
index e9bd7ec..a9321dd 100644
--- a/docs/magit.texi
+++ b/docs/magit.texi
@@ -2374,11 +2374,10 @@ sections are available.  There is one additional command.
 @kindex k
 @findex magit-process-kill
 This command kills the process represented by the section at point.
-@end table
 
-@defvar magit-git-debug
-This option controls whether additional reporting of git errors is
-enabled.
+@item @kbd{M-x magit-toggle-git-debug}
+@findex magit-toggle-git-debug
+This command toggles whether additional git errors are reported.
 
 Magit basically calls git for one of these two reasons: for
 side-effects or to do something with its standard output.
@@ -2387,25 +2386,18 @@ When git is run for side-effects then its output, including error
 messages, go into the process buffer which is shown when using @code{$}.
 
 When git's output is consumed in some way, then it would be too
-expensive to also insert it into this buffer, but when this
-option is non-nil and git returns with a non-zero exit status,
-then at least its standard error is inserted into this buffer.
-
-This is only intended for debugging purposes.  Do not enable this
-permanently, that would negatively affect performance.
-
-This is only intended for debugging purposes.  Do not enable this
-permanently, that would negatively affect performance.  Also note
-that just because git exits with a non-zero exit status and prints
-an error message that usually doesn't mean that it is an error as
-far as Magit is concerned, which is another reason we usually hide
-these error messages.  Whether some error message is relevant in
-the context of some unexpected behavior has to be judged on a case
-by case basis.
-
-The command @code{magit-toggle-git-debug} changes the value of this
-variable.
-@end defvar
+expensive to also insert it into this buffer, but with this command
+that can be enabled temporarily.  In that case, if git returns with
+a non-zero exit status, then at least its standard error is inserted
+into this buffer.
+
+Also note that just because git exits with a non-zero status and
+prints an error message, that usually doesn't mean that it is an
+error as far as Magit is concerned, which is another reason we
+usually hide these error messages.  Whether some error message is
+relevant in the context of some unexpected behavior has to be judged
+on a case by case basis.
+@end table
 
 @defvar magit-process-extreme-logging
 This option controls whether @code{magit-process-file} logs to the
@@ -11424,18 +11416,17 @@ When git is run for side-effects then its output, including error
 messages, go into the process buffer which is shown when using @code{$}.
 
 When git's output is consumed in some way, then it would be too
-expensive to also insert it into this buffer, but when this
-option is non-nil and git returns with a non-zero exit status,
-then at least its standard error is inserted into this buffer.
-
-This is only intended for debugging purposes.  Do not enable this
-permanently, that would negatively affect performance.  Also note
-that just because git exits with a non-zero exit status and prints
-an error message that usually doesn't mean that it is an error as
-far as Magit is concerned, which is another reason we usually hide
-these error messages.  Whether some error message is relevant in
-the context of some unexpected behavior has to be judged on a case
-by case basis.
+expensive to also insert it into this buffer, but with this command
+that can be enabled temporarily.  In that case, if git returns with
+a non-zero exit status, then at least its standard error is inserted
+into this buffer.
+
+Also note that just because git exits with a non-zero status and
+prints an error message, that usually doesn't mean that it is an
+error as far as Magit is concerned, which is another reason we
+usually hide these error messages.  Whether some error message is
+relevant in the context of some unexpected behavior has to be judged
+on a case by case basis.
 
 @item @kbd{M-x magit-toggle-verbose-refresh}
 @findex magit-toggle-verbose-refresh