bug#22984: 25.0.92; Typo in etc/DEBUG

bug#22984: 25.0.92; Typo in etc/DEBUG

[N. Jackson]

In line 75 of etc/DEBUG there is the following text:

  you can start GDB by typing "M-x GDB RET"

IIUC, this should say

  you can start GDB by typing "M-x gdb RET"

Additionally, it might be helpful if this file mentioned the "debugger"
that pops up when debug-on-error is non-nil. This "debugger" doesn't
seem to be a debugger at all, but just a help window with a backtrace in
it. If it is a debugger, then perhaps etc/DEBUG should say how to use
it, and if it isn't, then perhaps etc/DEBUG should say so?

Also, can one use `M-x gdb RET' in the same instance of Emacs that one
wishes to debug? I can think of good reasons why this might not work, so
I almost expect that it doesn't, but, on the other hand, it would be
convenient if it did work. So perhaps etc/DEBUG should explicitly say
that it can or cannot be done?

Thanks.

N.

bug#22984: 25.0.92; Typo in etc/DEBUG

[Eli Zaretskii]

> From: nljlistbox2@gmail.com (N. Jackson)
> Date: Fri, 11 Mar 2016 11:18:16 -0400
> 
> In line 75 of etc/DEBUG there is the following text:
> 
>   you can start GDB by typing "M-x GDB RET"
> 
> IIUC, this should say
> 
>   you can start GDB by typing "M-x gdb RET"

Thanks, fixed.

> Additionally, it might be helpful if this file mentioned the "debugger"
> that pops up when debug-on-error is non-nil.

That's not really what that file is about.

> This "debugger" doesn't seem to be a debugger at all, but just a
> help window with a backtrace in it.

No, it's a debugger.  See the node "Debugger" in the ELisp manual, it
is described there.

> Also, can one use `M-x gdb RET' in the same instance of Emacs that one
> wishes to debug?

No, of course not.  When you attach GDB to a program, GDB stops its,
so Emacs will stop responding, and you will not be able to continue
debugging.

But you can run a second instance of the same binary, and debug the
first instance from that second instance.  Perhaps this is what you
had in mind, and this is just a misunderstanding caused by the vague
meaning of "instance"?

bug#22984: 25.0.92; Typo in etc/DEBUG

[N. Jackson]

At 17:59 +0200 on Friday 2016-03-11, Eli Zaretskii wrote:
>
>> Additionally, it might be helpful if this file mentioned the "debugger"
>> that pops up when debug-on-error is non-nil.
>
> That's not really what that file is about.
>
>> This "debugger" doesn't seem to be a debugger at all, but just a
>> help window with a backtrace in it.
>
> No, it's a debugger.  See the node "Debugger" in the ELisp manual, it
> is described there.

I see. Thank you.

However, the file is named "DEBUG" and the title is "Debugging GNU
Emacs", so it is by no means obvious that this is not the right file to
look at.

So perhaps the title should be something like "Debugging GNU Emacs with
GDB", and perhaps it should start out by saying something along the
lines of

    This file is about debugging Emacs with GDB.  For information about
    the Lisp debugger and about Edebug (the source-level debugger for
    Emacs Lisp programs), see the node "Debugging" in the Elisp manual.

>> Also, can one use `M-x gdb RET' in the same instance of Emacs that one
>> wishes to debug?
>
> No, of course not.  When you attach GDB to a program, GDB stops its,
> so Emacs will stop responding, and you will not be able to continue
> debugging.
>
> But you can run a second instance of the same binary, and debug the
> first instance from that second instance.  Perhaps this is what you
> had in mind, and this is just a misunderstanding caused by the vague
> meaning of "instance"?

Hah, no. I've only ever used GDB from the command line. It seemed like
an (insanely) neat trick if you could run GDB in the same instance of
Emacs as one was debugging. It was my fuzzy thinking along with the
following sentence that led me astray:

    This will suggest the default binary to debug; if you are going to
    start a new Emacs process, change it as needed to point to the
    correct binary.

I think the full meaning of this sentence only becomes clear after one
reads the following sentence:

    Alternatively, if you want to attach the debugger to an already
    running Emacs process...

The problems with the first sentence are "you", "new", and "it". Perhaps
it could be made slightly clearer?

Perhaps something along the lines of:

    This will suggest the default binary for GDB to start; if you want
    GDB to start a different binary, change the suggestion as needed.
    Alternatively, if you want to attach GDB to an already running Emacs
    process...

Regards,
N.

bug#22984: 25.0.92; Typo in etc/DEBUG

[Eli Zaretskii]

> From: nljlistbox2@gmail.com (N. Jackson)
> Cc: 22984@debbugs.gnu.org
> Date: Fri, 11 Mar 2016 14:30:29 -0400
> 
>     This will suggest the default binary to debug; if you are going to
>     start a new Emacs process, change it as needed to point to the
>     correct binary.
> 
> I think the full meaning of this sentence only becomes clear after one
> reads the following sentence:
> 
>     Alternatively, if you want to attach the debugger to an already
>     running Emacs process...
> 
> The problems with the first sentence are "you", "new", and "it". Perhaps
> it could be made slightly clearer?
> 
> Perhaps something along the lines of:
> 
>     This will suggest the default binary for GDB to start; if you want
>     GDB to start a different binary, change the suggestion as needed.
>     Alternatively, if you want to attach GDB to an already running Emacs
>     process...

No, this is a false dichotomy.  The real issue here is that, when you
invoke GDB like that, the default binary it suggests is not emacs,
it's something else.  Try it, and you will see.

bug#22984: 25.0.92; Typo in etc/DEBUG

[N. Jackson]

At 20:39 +0200 on Friday 2016-03-11, Eli Zaretskii wrote:
>
>> From: nljlistbox2@gmail.com (N. Jackson)
>> Cc: 22984@debbugs.gnu.org
>> Date: Fri, 11 Mar 2016 14:30:29 -0400
>> 
>>     This will suggest the default binary to debug; if you are going to
>>     start a new Emacs process, change it as needed to point to the
>>     correct binary.
>> 
>> I think the full meaning of this sentence only becomes clear after one
>> reads the following sentence:
>> 
>>     Alternatively, if you want to attach the debugger to an already
>>     running Emacs process...
>> 
>> The problems with the first sentence are "you", "new", and "it". Perhaps
>> it could be made slightly clearer?
>> 
>> Perhaps something along the lines of:
>> 
>>     This will suggest the default binary for GDB to start; if you want
>>     GDB to start a different binary, change the suggestion as needed.
>>     Alternatively, if you want to attach GDB to an already running Emacs
>>     process...
>
> No, this is a false dichotomy.  The real issue here is that, when you
> invoke GDB like that, the default binary it suggests is not emacs,
> it's something else.  Try it, and you will see.

Yes, when I accepted the default, (something like `prog 3' IIRC), GDB
then complained that it didn't exist.

Anyway, if this is not what the paragraph is trying to say, then I don't
know what is intending to say, which still suggests that it could
benefit from some clarification.

In particular:

- the noun that "it" seems to stand for is the "suggestion" but that
  noun never appears, so grammatically "it" must be referring to something
  else -- but what?;

- the "you are going to start" seems wrong; won't it be GDB that will
  start the process?;

- the "new process" in the second case suggests that there is not a new
  process being started in the first (default) case.

I hope I'm not being too nitpicky (nor too obtuse) here. Just seems to
me there is a bit of opportunity here for an improvement.

Regards,
N.

bug#22984: 25.0.92; Typo in etc/DEBUG

[Eli Zaretskii]

> From: nljlistbox2@gmail.com (N. Jackson)
> Cc: 22984@debbugs.gnu.org
> Date: Fri, 11 Mar 2016 15:06:40 -0400
> 
> >> Perhaps something along the lines of:
> >> 
> >>     This will suggest the default binary for GDB to start; if you want
> >>     GDB to start a different binary, change the suggestion as needed.
> >>     Alternatively, if you want to attach GDB to an already running Emacs
> >>     process...
> >
> > No, this is a false dichotomy.  The real issue here is that, when you
> > invoke GDB like that, the default binary it suggests is not emacs,
> > it's something else.  Try it, and you will see.
> 
> Yes, when I accepted the default, (something like `prog 3' IIRC), GDB
> then complained that it didn't exist.
> 
> Anyway, if this is not what the paragraph is trying to say, then I don't
> know what is intending to say, which still suggests that it could
> benefit from some clarification.
> 
> In particular:
> 
> - the noun that "it" seems to stand for is the "suggestion" but that
>   noun never appears, so grammatically "it" must be referring to something
>   else -- but what?;
> 
> - the "you are going to start" seems wrong; won't it be GDB that will
>   start the process?;
> 
> - the "new process" in the second case suggests that there is not a new
>   process being started in the first (default) case.
> 
> I hope I'm not being too nitpicky (nor too obtuse) here. Just seems to
> me there is a bit of opportunity here for an improvement.

I'm not sure.  How a bout if you suggest an alternative wording,
perhaps it will explain better what you'd like to see there?

bug#22984: 25.0.92; Typo in etc/DEBUG

[N. Jackson]

At 21:42 +0200 on Friday 2016-03-11, Eli Zaretskii wrote:
>
> I'm not sure.  How a bout if you suggest an alternative wording,
> perhaps it will explain better what you'd like to see there?

The current text for the paragraph is this:

    We recommend using the GUI front-end for GDB provided by Emacs.
    With it, you can start GDB by typing "M-x gdb RET".  This will
    suggest the default binary to debug; if you are going to start a
    new Emacs process, change it as needed to point to the correct
    binary.  Alternatively, if you want to attach the debugger to an
    already running Emacs process, change the GDB command shown in
    the minibuffer to say this:

       gdb -i=mi -p PID

    where PID is the numerical process ID of the running Emacs
    process, displayed by system utilities such as 'top' or 'ps' on
    Posix hosts and Task Manager on MS-Windows.

It's the third sentence that's at issue due to the previously
mentioned ambiguities etc. I am suggesting something along the
following lines (but you have said IIUC that I have misunderstood
the intended meaning):

    We recommend using the GUI front-end for GDB provided by Emacs.
    With it, you can start GDB by typing "M-x gdb RET".  This will
    suggest the default binary for GDB to load; if you want GDB to
    load a different binary, change the suggestion as needed.  
    Alternatively, if you want to attach the debugger to an already
    running Emacs process, change the GDB command shown in the
    minibuffer to say this:

       gdb -i=mi -p PID

    where PID is the numerical process ID of the running Emacs
    process, displayed by system utilities such as 'top' or 'ps' on
    Posix hosts and Task Manager on MS-Windows.

bug#22984: 25.0.92; Typo in etc/DEBUG

[Eli Zaretskii]

> From: nljlistbox2@gmail.com (N. Jackson)
> Cc: 22984@debbugs.gnu.org
> Date: Fri, 11 Mar 2016 16:12:55 -0400
> 
>     We recommend using the GUI front-end for GDB provided by Emacs.
>     With it, you can start GDB by typing "M-x gdb RET".  This will
>     suggest the default binary for GDB to load; if you want GDB to
>     load a different binary, change the suggestion as needed.  
>     Alternatively, if you want to attach the debugger to an already
>     running Emacs process, change the GDB command shown in the
>     minibuffer to say this:
> 
>        gdb -i=mi -p PID
> 
>     where PID is the numerical process ID of the running Emacs
>     process, displayed by system utilities such as 'top' or 'ps' on
>     Posix hosts and Task Manager on MS-Windows.

How about the following variant?

  This will suggest the file name of the default binary to debug; if
  the suggested default is not the Emacs binary you want to debug,
  change the file name as needed.

(This avoids the potentially confusing word "load", and also makes it
clear we are talking about debugging Emacs, not some other program.)

bug#22984: 25.0.92; Typo in etc/DEBUG

[N. Jackson]

At 22:27 +0200 on Friday 2016-03-11, Eli Zaretskii wrote:
>
> How about the following variant?
>
>   This will suggest the file name of the default binary to debug; if
>   the suggested default is not the Emacs binary you want to debug,
>   change the file name as needed.
>
> (This avoids the potentially confusing word "load", and also makes it
> clear we are talking about debugging Emacs, not some other program.)

Yes, that's better. It clearly states its meaning.

Did you see the following suggestion in my earlier message. [I wasn't
sure if you'd missed it, or if you'd decided it wasn't valid.] This was
with regard to etc/DEBUG not being about the Elisp debugger.

At 14:30 -0400 on Friday 2016-03-11, N. Jackson wrote:
>
> However, the file is named "DEBUG" and the title is "Debugging GNU
> Emacs", so it is by no means obvious that this is not the right file to
> look at.

[to find information about the Elisp debugger]

> So perhaps the title should be something like "Debugging GNU Emacs with
> GDB", and perhaps it should start out by saying something along the
> lines of
>
>     This file is about debugging Emacs with GDB.  For information about
>     the Lisp debugger and about Edebug (the source-level debugger for
>     Emacs Lisp programs), see the node "Debugging" in the Elisp manual.

Regards,
N.

bug#22984: 25.0.92; Typo in etc/DEBUG

[Eli Zaretskii]

> From: nljlistbox2@gmail.com (N. Jackson)
> Cc: 22984@debbugs.gnu.org
> Date: Fri, 11 Mar 2016 17:18:56 -0400
> 
> At 22:27 +0200 on Friday 2016-03-11, Eli Zaretskii wrote:
> >
> > How about the following variant?
> >
> >   This will suggest the file name of the default binary to debug; if
> >   the suggested default is not the Emacs binary you want to debug,
> >   change the file name as needed.
> >
> > (This avoids the potentially confusing word "load", and also makes it
> > clear we are talking about debugging Emacs, not some other program.)
> 
> Yes, that's better. It clearly states its meaning.

Pushed, thanks.

> Did you see the following suggestion in my earlier message. [I wasn't
> sure if you'd missed it, or if you'd decided it wasn't valid.] This was
> with regard to etc/DEBUG not being about the Elisp debugger.

We only mention the Lisp debugger once in the entire file.  I added a
reference to the ELisp manual there.