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

[Joel Brobecker <brobecker at adacore dot com>]

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: mcas-doc.diff
Description: Text document