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

[Joel Brobecker]

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
-------------- next part --------------
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''