Re: [PATCH v2] gdb: improve usage strings

[Pedro Alves <palves at redhat dot com>]

On 08/13/2012 09:28 PM, Doug Evans wrote:
> On Sun, Aug 12, 2012 at 7:05 PM, Mike Frysinger <vapier@gentoo.org> wrote:
>>    c = add_com ("signal", class_run, signal_command, _("\
>> -Continue program giving it signal specified by the argument.\n\
>> -An argument of \"0\" means continue program without giving it a signal."));
>> +Continue program and simultaneously send it the specified signal.\n\
>> +Usage: signal SIGNAL\n\
>> +An argument of \"0\" means continue the program without sending it a signal."));
>>    set_cmd_completer (c, signal_completer);
> 
> That's ok I guess.  How about "Continue program with the specified signal." ?

Agreed.  I was catching on up the thread, and thought of suggest this.  I could
swear that's terminology we already use.  Ah, at least here:

...
@item C @var{sig}@r{[};@var{addr}@r{]}
@cindex @samp{C} packet
Continue with signal @var{sig} (hex signal number).  If
^^^^^^^^^^^^^^^^^^^^
@samp{;@var{addr}} is omitted, resume at same address.
...
You can also use the @code{signal} command to prevent your program from
seeing a signal, or cause it to see a signal it normally would not see,
or to give it any signal at any time.  For example, if your program stopped
due to some sort of memory reference error, you might store correct
values into the erroneous variables and continue, hoping to see more
execution; but your program would probably terminate immediately as
a result of the fatal signal once it saw the signal.  To prevent this,
you can continue with @samp{signal 0}.  @xref{Signaling, ,Giving your
        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Program a Signal}.
...

Consistency between help and manual is good.

> 
> Also, it would be good to augment the docs for "sig 0" to denote it
> can be used to resume a program and discard the signal that is pending
> for it, and would otherwise receive if you did a "continue".  It's
> kinda implicit in the existing wording, but I've seen a few cases
> where more clarity would have helped.
> 
> How about:
> 
> An argument of "0" means continue the program without sending it a signal.
> This is useful in cases where the program stopped because of a signal,
> and you want to resume the program and discard the signal.

-- 
Pedro Alves