Merge from origin/emacs-26

71be806 ; * etc/DEBUG: Minor clarification.
4403f89 Update the Emacs FAQ
40b3317 * etc/DEBUG: Minor copyedits.
850ff18 Clarify wording of NS drag n drop documentation
343d70b1 Improve kill-related documentation (bug#31209)
0b43224 * lisp/simple.el (region-extract-function): Don't hide the 'n...
d6e2c59 Fix pre- and post-command-hook errors in term.el
6cf83131e * doc/lispref/display.texi (Glyphless Chars): Fix grammar.
88d178c Fix macOS drag n drop event documentation

1 files changed, 17 insertions, 6 deletions

diff --git a/etc/DEBUG b/etc/DEBUG
index 49764fc9137..aeb447bae33 100644
--- a/etc/DEBUG
+++ b/etc/DEBUG
@@ -43,6 +43,11 @@ created in the 'src' directory.
 
 *** Configuring GDB
 
+To start GDB to debug Emacs, you can simply type "gdb ./emacs RET" at
+the shell prompt (assuming you do that from the directory of the Emacs
+executable, usually the 'src' sub-directory of the Emacs tree).
+However, we recommend starting GDB from Emacs, see below.
+
 When you debug Emacs with GDB, you should start GDB in the directory
 where the Emacs executable was made (the 'src' directory in the Emacs
 source tree).  That directory has a .gdbinit file that defines various
@@ -52,16 +57,19 @@ Emacs Redisplay problems".)
 
 Starting the debugger from Emacs, via the "M-x gdb" command (described
 below), when the current buffer visits one of the Emacs C source files
-will automatically start GDB in the 'src' directory.
+will automatically start GDB in the 'src' directory.  If you invoke
+"M-x gdb" from a buffer whose default directory is different, such as
+from the "*scratch*" buffer, you can change the default directory with
+the "M-x cd" command before starting the debugger.
 
-Some GDB versions by default do not automatically load .gdbinit files
-in the directory where you invoke GDB.  With those versions of GDB,
-you will see a warning when GDB starts, like this:
+Recent GDB versions by default do not automatically load .gdbinit
+files in the directory where you invoke GDB.  With those versions of
+GDB, you will see a warning when GDB starts, like this:
 
   warning: File ".../src/.gdbinit" auto-loading has been declined by your `auto-load safe-path' set to "$debugdir:$datadir/auto-load".
 
 The simplest way to fix this is to add the following line to your
-~/.gdbinit file:
+~/.gdbinit file (creating such a file if it doesn't already exist):
 
   add-auto-load-safe-path /path/to/emacs/src/.gdbinit
 
@@ -133,9 +141,12 @@ to the debugger".
 
 You are now ready to start your debugging session.
 
+*** Running Emacs from GDB
+
 If you are starting a new Emacs session, type "run", followed by any
 command-line arguments (e.g., "-Q") into the *gud-emacs* buffer and
-press RET.
+press RET.  If you ran GDB outside of Emacs, type "run" followed by
+the command-line arguments at the GDB prompt instead.
 
 If you attached the debugger to a running Emacs, type "continue" into
 the *gud-emacs* buffer and press RET.