Re: [RFA/doco] document "set/show multiple-choice-auto-select"

[Eli Zaretskii <eliz at gnu dot org>]

> Date: Thu, 24 Jan 2008 13:32:56 -0800
> From: Joel Brobecker <brobecker@adacore.com>
> 
> I usually say that I'll send a doco update after a patch is accepted,
> but in this case, for once I'm sending the doco patch before I started
> working on the patch itself :).

Thanks!

> Right now, the documentation about menus is included as part of
> breakpoint support. I updated the documentation within that context
> for now.  I'm not sure how to extend the documentation to cover
> the cases where breakpoints are not involved yet.  One way of
> doing it would be to extract the current section out of the breakpoint
> documentation and make it more general. Another way would be to
> leave it as is, and then make another section somewhere else (somewhere
> inside "Examining Data/Program_Variables" that explains what happens
> when an ambiguous symbol name is used, with a reference to the
> Breakpoints Menu node.
> 
> I think that the first option is a little bit better, but it's hard
> to tell.

I also think the first option is better.  In fact, I did just that
recently for the description of ``locations'' in GDB, and didn't have
any major problems targeting the several commands that use them.  In
the few cases where the difference mattered, I simply explained the
effect in each context.

A few comments about your patch:

> +By default when the location expression is ambiguous, @value{GDBN}
> +automatically selects all possible locations.  But this behavior
> +can be configured so that a menu is of numbered choices for different
> +possible breakpoints is displayed (see below).

Something is wrong with the last sentence (two uses of ``is'' in
particular).  What did you want to say?

> In that case, the @value{GDBN} waits

"the" should be removed here.

> +By default when the location expression is ambiguous, @value{GDBN}
> +automatically selects all possible locations.  But this behavior
> +can be configured so that a menu is of numbered choices for different
> +possible breakpoints is displayed (see below).

I suggest to explicitly mention the name of the option here.

> +Typing @kbd{1} sets a breakpoint at each possible locations and typing

It's probably better to say

  Typing @kbd{1 @key{RET}}

Since you need to type Enter after 1, right?

> +@item set multiple-choice-auto-select @var{mode}
> +@cindex menu auto select
> +This option allows you to adjust the debugger behavior when a location
> +expression is ambiguous.  When set to @var{off}, the debugger does not

The last sentence should read

  When @var{mode} is set to @code{off},

@var is only applicable to parameters whose names stand for some
specific value.  "off" is such a specific value, so it's wrong to use
@var with it.  Also, when you say "when set to off, the debugger ...",
it sounds like you are saying that the debugger is set to "off", which
is not what you want.

I also think that the default behavior should be described first, so
please make "all" the first value you describe, and please state right
away that it's the default (if that is so, see below):

  When @var{mode} is set to @code{all} (the default), ...

> By default, this option is set to @var{all}.

Really?  So your patch makes GDB behave differently by default than it
did before?  I rather thought the default was "off", was I dreaming?

> +@item show multiple-choice-auto-select
> +Show the current value of the multiple-choice-auto-select setting.

The name of the option should be in @code.