Re: PR7580 - Command to force abort when internal error

[Eli Zaretskii <eliz at gnu dot org>]

> From: Pedro Alves <pedro@codesourcery.com>
> Date: Wed, 7 Jan 2009 21:59:29 +0000
> Cc: gdb-patches@sourceware.org,
>  Eli Zaretskii <eliz@gnu.org>
> 
> Eli, is the documentation piece OK?

Yes, but I have a few comments.  See below.

> +const char internal_problem_ask[] = "ask";
> +const char internal_problem_yes[] = "yes";
> +const char internal_problem_no[] = "no";

Don't we want these strings to be translatable?  The questions we ask
about what to do are.

> +/* When GDB reports an internal problem (error or warning) it gives
> +   the user the opportunity to quit GDB and/or create a core file of
> +   the current debug session.  This function registers a few commands
> +   that make it possible to specify that GDB should always or never
> +   quit or create a core file, without asking.  The commands look
> +   like:
> +
> +   maint set PROBLEM-NAME quit ask|yes|no
> +   maint show PROBLEM-NAME quit
> +   maint set PROBLEM-NAME corefile ask|yes|no
> +   maint show PROBLEM-NAME corefile
> +
> +   Where PROBLEM-NAME is currently "internal-error" or
> +   "internal-warning".  */

I'd love to have this important infrastructure documented in
gdbint.texinfo.

> +  set_doc = xstrprintf (_("Configure what GDB does when an %s is detected."),
> +			problem->name);
> +
> +  show_doc = xstrprintf (_("Show what GDB does when an %s is detected."),
> +			 problem->name);

I would lose the "an" part: this is general infrastructure, so even if
all the currently known problem names fit "an", we cannot guarantee
that to be so in the future.  There's no need here for an article,
anyway, as something like

   Show what GDB does when FOO is detected.

sounds perfectly correct English to me.

> +  set_doc = xstrprintf (_("\
> +Set whether GDB should quit when an %s is detected"),
> +			problem->name);
> +  show_doc = xstrprintf (_("\
> +Show whether GDB will quit when an %s is detected"),
> +			 problem->name);

Same here.

> +  set_doc = xstrprintf (_("\
> +Set whether GDB should create a core file of GDB when an %s is detected"),
> +			problem->name);
> +  show_doc = xstrprintf (_("\
> +Show whether GDB will create a core file of GDB when an %s is detected"),
> +			 problem->name);

And here.

> +@kindex maint set internal-error quit
> +@kindex maint show internal-error quit
> +@kindex maint set internal-error corefile
> +@kindex maint show internal-error corefile
> +@kindex maint set internal-warning quit
> +@kindex maint show internal-warning quit
> +@kindex maint set internal-warning corefile
> +@kindex maint show internal-warning corefile
> +@item maint set internal-error quit [ask|yes|no]
> +@itemx maint show internal-error quit
> +@itemx maint set internal-error corefile [ask|yes|no]
> +@itemx maint show internal-error corefile
> +@itemx maint set internal-warning quit [ask|yes|no]
> +@itemx maint show internal-warning quit
> +@itemx maint set internal-warning corefile [ask|yes|no]
> +@itemx maint show internal-warning corefile

There's no need for listing all the possible ACTIONs here.  It is
enough to say

 @kindex maint set internal-error
 @kindex maint show internal-error
 @item maint set internal-error @var{action} [ask|yes|no]
 @itemx maint show internal-error @var{action}

and then list all the possible values of @var{action} and explain
them.  As a nice side-effect, this will always make the index less
cluttered.

I would also add here another index entry, for those who don't
remember or don't know the command's name, but are still looking for
this information.  How about

 @cindex @value{GDBN} internal error
 @cindex internal errors, control of @value{GDBN} behavior

?

Other than that, this is fine; thanks.