Re: [PATCH] gdb: improve usage strings

[Eli Zaretskii <eliz@gnu.org>]

> From: Mike Frysinger <vapier@gentoo.org>
> Date: Sat, 11 Aug 2012 12:54:40 -0400
> 
> This adds Usage strings to a bunch of commands, tweaks the grammar in a
> few, and improves the help text for the handle command.

Thanks.

>    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 by sending it the specified signal.\n\

This "by sending it" is AFAIU inaccurate: we don't continue program
_by_ sending it the signal, we continue the program _and_ send it the
signal.  I actually don't see anything wrong with the original
wording.

>    add_com ("finish", class_run, finish_command, _("\
>  Execute until selected stack frame returns.\n\
> +Usage: finish\n\
>  Upon return, the value returned is printed and put in the value history."));

Does this "usage" really add any information?

>    add_com ("next", class_run, next_command, _("\
>  Step program, proceeding through subroutine calls.\n\
> +Usage: next [N]\n\
>  Like the \"step\" command as long as subroutine calls do not happen;\n\
>  when they do, the call is treated as one instruction.\n\
> -Argument N means do this N times (or till program stops for another \
> +Argument N means step N times (or till program stops for another \

Isn't it better to say "N source lines"?

Btw, I find this entire doc string completely obfuscated.  How about
this instead:

  Step program until it reaches a different source line.
  Usage: next [N]
  Unlike "step", if the current source line calls a subroutine,
  this command does not enter the subroutine, but instead steps over
  the call, in effect treating it as a single source line.