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

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

[Joel Brobecker]

[-- Attachment #1: Type: text/plain, Size: 2460 bytes --]

Hi Eli,

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 :).  The patch will follow soon, but the
general principal behind the change is accepted I think, so it's safe
to work on the documentation a bit in advance.

I expanded a bit on the "Breakpoint Menus" section, giving more details
as to when a multiple-choice menu could happen in the context of
breakpoints.  This is because the text as it is written now assumes
that you only get the menu when doing "break function_name", which
is incorrect. I tried to make the text better as well as introducing
the new set/show command.

The problem I'm having which I haven't solved in this patch is that
the menu can be needed in other circumstances than breakpoints. During
general expression evaluations such as "print function_name" for
instance, where function_name is ambiguous.  In Ada, we also print
a menu and ask the user to choose, except that the "all" choice
is not available and the user can choose one and only one choice.
In C++, I *think* that one symbol at random gets selected, but
I'd appreciate if this could be confirmed.  The documentation does
not cover that aspect yet.

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. One single general section allows us to have all the
information in one single place.  But the generality of it might
make it harder to understand in practice. With two different locations,
we can be more practical in our explanations. What do you think?

2008-01-24  Joel Brobecker  <brobecker@adacore.com>

        * gdb.texinfo (Breakpoint Menus): Improve documentation.
        Add documentation for set/show multiple-choice-auto-select.

Tested by rebuilding the HTML documentation.

-- 
Joel

[-- Attachment #2: mcas-doc.diff --]
[-- Type: text/plain, Size: 3823 bytes --]

Index: gdb.texinfo
===================================================================
RCS file: /cvs/src/src/gdb/doc/gdb.texinfo,v
retrieving revision 1.458
diff -u -p -r1.458 gdb.texinfo
--- gdb.texinfo	19 Jan 2008 13:37:13 -0000	1.458
+++ gdb.texinfo	24 Jan 2008 21:02:37 -0000
@@ -3798,19 +3798,31 @@ end
 @subsection Breakpoint Menus
 @cindex overloading
 @cindex symbol overloading
+@cindex Ada generics
+@cindex C++ templates
 
-Some programming languages (notably C@t{++} and Objective-C) permit a
-single function name
-to be defined several times, for application in different contexts.
-This is called @dfn{overloading}.  When a function name is overloaded,
-@samp{break @var{function}} is not enough to tell @value{GDBN} where you want
-a breakpoint.  You can use explicit signature of the function, as in
-@samp{break @var{function}(@var{types})}, to specify which
-particular version of the function you want.  Otherwise, @value{GDBN} offers
-you a menu of numbered choices for different possible breakpoints, and
-waits for your selection with the prompt @samp{>}.  The first two
-options are always @samp{[0] cancel} and @samp{[1] all}.  Typing @kbd{1}
-sets a breakpoint at each definition of @var{function}, and typing
+A breakpoint location expression (@ref{Specify Location}) is sometimes
+ambiguous.  For instance, some programming languages (notably Ada,
+C@t{++} and Objective-C) permit a single function name to be defined
+several times, for application in different contexts.  This is called
+@dfn{overloading}.  Another example involving Ada is generics.  A
+@dfn{generic package} is similar to C@t{++} templates and is typically
+instantiated several times, resulting in the same function name being
+defined in different contexts.
+
+In some cases and depending on the language, it is possible to make
+the location unambiguous.  For instance in C@t{++}, you can specify
+the signature of the function you want to break on, as in @samp{break
+@var{function}(@var{types})}.  In Ada, using the fully qualified
+name of your function often makes the location expression unambiguous.
+
+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).  In that case,
+the @value{GDBN} waits for your selection with the prompt @samp{>}.
+The first two options are always @samp{[0] cancel} and @samp{[1] all}.
+Typing @kbd{1} sets a breakpoint at each possible locations and typing
 @kbd{0} aborts the @code{break} command without setting any new
 breakpoints.
 
@@ -3841,6 +3853,26 @@ Use the "delete" command to delete unwan
 @end group
 @end smallexample
 
+@table @code
+@kindex set multiple-choice-auto-select
+@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
+perform any automatic selection, and instead asks you to select from
+a multiple-choice menu which choices should be used.  When set to @var{all}, 
+@value{GDBN} automatically selects all possible choices.  This is strictly
+equivalent to selecting choice @var{1} in the multiple-choice menu,
+except that the menu is not displayed.  And finally, this option can be
+set to @var{cancel}, which causes the abort of the command if the
+location expression is ambiguous.  By default, this option is set to
+@var{all}.
+
+@kindex show multiple-choice-auto-select
+@item show multiple-choice-auto-select
+Show the current value of the multiple-choice-auto-select setting.
+@end table
+
 @c  @ifclear BARETARGET
 @node Error in Breakpoints
 @subsection ``Cannot insert breakpoints''

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

[Nick Roberts]

 > 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 :).  The patch will follow soon, but the
 > general principal behind the change is accepted I think, so it's safe
 > to work on the documentation a bit in advance.

I would guess that your proposed patch will overlap with one that I've
recently submitted:

http://sourceware.org/ml/gdb-patches/2008-01/msg00421.html

-- 
Nick                                           http://www.inet.net.nz/~nickrob

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

[Joel Brobecker]

>  > 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 :).  The patch will follow soon, but the
>  > general principal behind the change is accepted I think, so it's safe
>  > to work on the documentation a bit in advance.
> 
> I would guess that your proposed patch will overlap with one that I've
> recently submitted:
> 
> http://sourceware.org/ml/gdb-patches/2008-01/msg00421.html

I'm sorry - I am still jetlaged from my 36h trip and 12h time difference,
so I may be even more obtuse than usual ;-). IIUC, you are trying to
improve the situation in MI regarding multiple-location breakpoints,
right? Where is the overlapping? In the fact that you'll have to
modify the documentation in the same area? You'll have to forgive me,
I don't know the MI protocol apart from the general principles behind
it. This may also explain my questions...

-- 
Joel

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

[Nick Roberts]

 > > I would guess that your proposed patch will overlap with one that I've
 > > recently submitted:
 > > 
 > > http://sourceware.org/ml/gdb-patches/2008-01/msg00421.html
 > 
 > I'm sorry - I am still jetlaged from my 36h trip and 12h time difference,
 > so I may be even more obtuse than usual ;-). IIUC, you are trying to
 > improve the situation in MI regarding multiple-location breakpoints,
 > right? Where is the overlapping? In the fact that you'll have to
 > modify the documentation in the same area? You'll have to forgive me,
 > I don't know the MI protocol apart from the general principles behind
 > it. This may also explain my questions...
 
The thread I refer to is about breakpoint menus and it follows (after some
delay) a bug report by Dodji Seketeli (nemiver).  Vladimir Prus has
suggested that we fix this in another way but I just thought I'd draw your
attention to it.  You don't need to know much about MI.  It just accepts
all the overloaded breakpoints when MI is the underlying interpreter.  Perhaps
I should have pointed here:

http://sourceware.org/ml/gdb/2008-01/msg00104.html

-- 
Nick                                           http://www.inet.net.nz/~nickrob

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

[Eli Zaretskii]

> 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.