Re: Revise etc/DEBUG documentation

[Alain Schneble]

Eli Zaretskii <address@hidden> writes:

> 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.

Thanks for reading my message. I was confused with how different the
behavior regarding signals is when debugging Emacs using GDB in all the
different variations (terminal/console, GUI, POSIX, MS-Windows).  Before
looking into Emacs and GDB sources in detail, I wasn't able to figure
out why it behaves differently.  That was the main idea behind the
proposed change.  To document these nuances.  Apparently, I missed the
point.  Sorry.

> 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.

I basically agree.  But 1) there was already some information there and
2) some minimal hints really helps one (or at least me) to start off.
But it's probably hard to find a good boundary where to stop.  I guess
your point is that I passed it.

> 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.

Actually, I tried this first but I had the impression that I start
mixing stuff that somehow does not belong together.  That's why I
started to restructure it.

> 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.

Because it allows one to hit C-c in GDB, do some changes such as adding
breakpoints and then continue.  With 'pass' it would terminate Emacs if
it is run as a GUI application.  When run in a terminal, it does not
terminate.  A nuance.

>> +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.

True.  But I think such background information would have helped me a
lot.  I don't think that DEBUG should apriori not include any such
details that might help one to understand the interaction between the
User, Emacs and GDB.

>> +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.

To be honest, I don't understand this either.  But this was there
before.  I just took it over and rephrased it slightly.  For example C-z
in Gnome just minimizes the window (Emacs frame) AFAIK, but doesn't stop
Emacs.  Do you know what C-z usually does in X window with a GUI
application?  Does it send a signal to it?

>> +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?

separate terminal => set new-console 1.  I should have used the term
console rather than terminal here, I guess.

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

With new-console 1, when starting Emacs GUI, the console is visible as a
separate window in MS-Windows.  And it is this console window that can
be used to enter Ctrl-c or Ctrl-Break, even though we are running Emacs
as a GUI application.  A nuance.

> 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.
That it behaves differently than on POSIX, where a SIGINT would
terminate Emacs when running in "GUI mode".  A nuance.

>> +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.
Again, separate terminal => set new-console 1

>>                                          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.
All processes sharing the same console will receive the C-c event.  In
that case GDB doesn't have to escape to using DebugBreakProcess.  GDB
just ignores C-c and Emacs will receive it anyway.  This was another
thing that confused me.  That depenting on 'set new-console' setting,
GDB signals either a SIGINT (due to C-c being received by Emacs) or a
SIGTRAP (due to DebugBreakProcess) for the same initial C-c/SIGINT
event.  A nuance.

> Thanks again for working on this.

I hope I could clarify at least the intent of my change.  If you are
still confused, I'll restart and try what you proposed: To find a way to
only add missing information in the first place.  And to not rephrase
existing content.

Thanks for your input.  I appreciate it.