Merge from origin/emacs-25

0ffc9ce Update admin/authors.el
0ad7410 Update Antinews in ELisp manual
ea0f750 Fix comments on window height macros
0bbdeed Fix 'url-http-create-request' when cookies are used
0045998 Fix cross reference in frames.texi
1392894 ; * etc/DEBUG: Minor copyedits.
304a5c8 ; * etc/DEBUG: Improve documentation of getting control to GDB.
56bf7d7 Fix regexp-opt documentation (bug #17862)
803ad6f ; Fix documentation of seq-subseq
ed4530d * lisp/emacs-lisp/gv.el (gv-ref): Fix example of PLACE in doc...
88ea396 ; Spelling fixes
17197d0 Fix tags-query-replace docstring
80a7f8b Clarify documentation of precision in format specs
88a5052 Improve and clarify documentation of subprocesses
89eb09f * etc/PROBLEMS: Mention gnutls-cli 3.5.3 (Bug#24247).

# Conflicts:
#	etc/PROBLEMS
#	src/process.c

1 files changed, 53 insertions, 22 deletions

diff --git a/etc/DEBUG b/etc/DEBUG
index 656e29a8b74..03efa3b10dd 100644
--- a/etc/DEBUG
+++ b/etc/DEBUG
@@ -190,24 +190,44 @@ kick in, provided that you run under GDB.
 
 ** Getting control to the debugger
 
+Setting a breakpoint in a strategic place, after loading Emacs into
+the debugger, but before running it, is the most efficient way of
+making sure control will be returned to the debugger when you need
+that.
+
 'Fsignal' is a very useful place to put a breakpoint in.  All Lisp
 errors go through there.  If you are only interested in errors that
-would fire the debugger, breaking at 'maybe_call_debugger' is useful.
+would fire the Lisp debugger, breaking at 'maybe_call_debugger' is
+useful.
+
+Another technique for get control to the debugger is to put a
+breakpoint in some rarely used function.  One such convenient function
+is Fredraw_display, which you can invoke at will interactively with
+"M-x redraw-display RET".
 
-It is useful, when debugging, to have a guaranteed way to return to
-the debugger at any time.  When using X, this is easy: type C-z at the
-window where Emacs is running under GDB, and it will stop Emacs just
-as it would stop any ordinary program.  When Emacs is running in a
-terminal, things are not so easy.
+It is also useful to have a guaranteed way to return to the debugger
+at any arbitrary time.  When using X, this is easy: type C-z at the
+window where you are interacting with GDB, and it will stop Emacs just
+as it would stop any ordinary program.  (This doesn't work if GDB was
+attached to a running Emacs process; in that case, you will need to
+type C-z to the shell window from which Emacs was started, or use the
+"kill -TSTP" method described below.)
+
+When Emacs is displaying on a text terminal, things are not so easy,
+so we describe the various alternatives below (however, those of them
+that use signals only work on Posix systems).
 
 The src/.gdbinit file in the Emacs distribution arranges for SIGINT
-(C-g in Emacs) to be passed to Emacs and not give control back to GDB.
-On modern POSIX systems, you can override that with this command:
+(C-g in Emacs on a text-mode frame) to be passed to Emacs and not give
+control back to GDB.  On modern systems, you can override that with
+this command:
 
    handle SIGINT stop nopass
 
 After this 'handle' command, SIGINT will return control to GDB.  If
 you want the C-g to cause a QUIT within Emacs as well, omit the 'nopass'.
+See the GDB manual for more details about signal handling and the
+'handle' command.
 
 A technique that can work when 'handle SIGINT' does not is to store
 the code for some character into the variable stop_character.  Thus,
@@ -216,26 +236,37 @@ the code for some character into the variable stop_character.  Thus,
 
 makes Control-] (decimal code 29) the stop character.
 Typing Control-] will cause immediate stop.  You cannot
-use the set command until the inferior process has been started.
-Put a breakpoint early in 'main', or suspend the Emacs,
-to get an opportunity to do the set command.
+use the set command until the inferior process has been started, so
+start Emacs with the 'start' command, to get an opportunity to do the
+above 'set' command.
 
-Another technique for get control to the debugger is to put a
-breakpoint in some rarely used function.  One such convenient function
-is Fredraw_display, which you can invoke at will interactively with
-"M-x redraw-display RET".
+On a Posix host, you can also send a signal using the 'kill' command
+from a shell prompt, like this:
 
-When Emacs is running in a terminal, it is sometimes useful to use a separate
-terminal for the debug session.  This can be done by starting Emacs as usual,
-then attaching to it from gdb with the 'attach' command which is explained in
-the node "Attach" of the GDB manual.
+   kill -TSTP Emacs-PID
 
-On MS-Windows, you can start Emacs in its own separate terminal by
-setting the new-console option before running Emacs under GDB:
+where Emacs-PID is the process ID of Emacs being debugged.  Other
+useful signals to send are SIGUSR1 and SIGUSR2; see "Error Debugging"
+in the ELisp manual for how to use those.
+
+When Emacs is displaying on a text terminal, it is useful to have a
+separate terminal for the debug session.  This can be done by starting
+Emacs as usual, then attaching to it from gdb with the 'attach'
+command which is explained in the node "Attach" of the GDB manual.
+
+On MS-Windows, you can alternatively start Emacs from its own separate
+console by setting the new-console option before running Emacs under
+GDB:
 
   (gdb) set new-console 1
   (gdb) run
 
+If you do this, then typing C-c or C-BREAK into the console window
+through which you interact with GDB will stop Emacs and return control
+to the debugger, no matter if Emacs displays GUI or text-mode frames.
+This is the only reliable alternative on MS-Windows to get control to
+the debugger, besides setting breakpoints in advance.
+
 ** Examining Lisp object values.
 
 When you have a live process to debug, and it has not encountered a
@@ -848,7 +879,7 @@ directed to the xterm window you opened above.
 Similar arrangement is possible on a character terminal by using the
 'screen' package.
 
-On MS-Windows, you can start Emacs in its own separate terminal by
+On MS-Windows, you can start Emacs in its own separate console by
 setting the new-console option before running Emacs under GDB:
 
   (gdb) set new-console 1