Re: Revise etc/DEBUG documentation

[Eli Zaretskii <eliz@gnu.org>]

> From: Alain Schneble <a.s@realize.ch>
> Date: Sat, 3 Sep 2016 12:31:56 +0200
> 
> While studying how signals are handled in Emacs (both when run under a
> POSIX system as well as MS-Windows) and also how GDB deals with them, I
> thought it would be worth to revise the section 'Getting control to the
> debugger' in etc/DEBUG to include some more information about how
> signals can be used to interrupt Emacs debuggee and return control back
> to GDB.
> 
> Would you mind installing this patch?  Any comments are welcome.

Thanks.

Frankly, I'm a bit confused after reading the changes.  Some of them
rephrase what was already in DEBUG, others rearrange existing text
(and also rephrase it a bit), still others describe features that I
either didn't understand or they will work only under specific
circumstances.  I guess I don't really understand the main idea behind
the proposed changes.

I also am not sure we should repeat here stuff that is basic GDB
usage.  Any such descriptions are bound to be incomplete and thus
inaccurate.  It is better to refer the readers to the GDB manual, if
they are not already proficient.

How about if we first add any missing information, and leave
rephrasing for a separate patch?  Or maybe just tell what you think is
missing in the current version, and let's take it from there.

Some specific comments and questions follow.

> +When Emacs is running under a window system, reception of a SIGINT and
> +SIGQUIT will cause it to terminate.  It might therefore be useful to
> +configure the 'handle' command for those signals to use 'nopass', to
> +prevent Emacs from terminating on reception of such signals.

I don't understand why is this useful.

> +When using a window system, there is no reason for Emacs to handle C-g
> +as a SIGINT, as keyboard input is processed by the window system's
> +message pump.  Hence, no signal is sent as a response to a C-g.

This explains how Emacs works, but I'm not sure it belongs in DEBUG.

> +When using X, 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.

The "window where Emacs is running under GDB" part is IMO confusing: I
couldn't figure out what window does this refer to.  There might not
be such a window at all, AFAIU.

> +On MS-Windows, starting Emacs in its own separate terminal even when
> +running as a GUI application will allow you to send a Ctrl-c or
> +Ctrl-Break to the console.  GDB treats them as a SIGINT, but Emacs
> +won't terminate as it ignores these events.

This also left me confused.  First, what do you mean by "separate
terminal" in this case?  Up to here, when DEBUG says "terminal", it
means "text terminal", but here you are talking about GUI sessions, so
what is a "separate terminal" applicable to the GUI Emacs session on
MS-Windows?

Next, what do you mean by "send a Ctrl-c or +Ctrl-Break to the
console"?  What console is alluded to here?

Finally, what does the "GDB treats them as a SIGINT, but Emacs won't
terminate as it ignores these events" part want to tell?  I couldn't
figure that out.

> +On MS-Windows, GDB will turn a C-c into a DebugBreakProcess call if
> +Emacs is running in a separate terminal

Here's the "separate terminal" thing once again.

>                                          or it will just ignore it
> +otherwise, as the event will be received by Emacs anyway when running
> +under the same terminal as GDB.

This part is also confusing.  And I wonder why the signal-process
feature is not mentioned here.

Thanks again for working on this.