Re: [RFA/doco] Document the new default for "set print frame-arguments"

[Joel Brobecker <brobecker at adacore dot com>]

[ENOPATCH, sorry]

This is a slight change of behavior, with a patch posted there:

    http://www.sourceware.org/ml/gdb-patches/2009-03/msg00532.html

Here is the associated documentation update. I added a little reference
to this command in the "Backtrace" node to make it easier to find
this command as well as understanding what the "..." means. And I also
changed the command documentation a bit to reflect the new default.

2009-04-02  Joel Brobecker  <brobecker@adacore.com>

        * gdb.texinfo (Backtrace): Add a parameter in frame 1 of the first
        example, and add a small explanation about it.
        (Print Settings): Change the documentation of the "set print
        frame-arguments" to reflect the fact that the default is now "scalars".

OK to commit?

Thanks,
-- 
Joel

commit 5f6c78d2342a55d4932c2a3580a75fd5d3132d6b
Author: Joel Brobecker <brobecker@adacore.com>
Date:   Wed Apr 1 16:03:27 2009 -0700

        * gdb.texinfo (Backtrace): Add a parameter in frame 1 of the first
        example, and add a small explanation about it.
        (Print Settings): Change the documentation of the "set print
        frame-arguments" to reflect the fact that the default is now "scalars".

diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index eaac24f..f4aa21d 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -5179,7 +5179,7 @@ Here is an example of a backtrace.  It was made with the command
 @group
 #0  m4_traceon (obs=0x24eb0, argc=1, argv=0x2b8c8)
     at builtin.c:993
-#1  0x6e38 in expand_macro (sym=0x2b600) at macro.c:242
+#1  0x6e38 in expand_macro (sym=0x2b600, data=...) at macro.c:242
 #2  0x6840 in expand_token (obs=0x0, t=177664, td=0xf7fffb08)
     at macro.c:71
 (More stack frames follow...)
@@ -5191,6 +5191,13 @@ The display for frame zero does not begin with a program counter
 value, indicating that your program has stopped at the beginning of the
 code for line @code{993} of @code{builtin.c}.
 
+@noindent
+The value of parameter @code{data} in frame 1 has been replaced by
+@code{@dots{}}.  By default, @value{GDBN} prints the value of a parameter
+only if it is a scalar (integer, pointer, enumeration, etc).  See command
+@kbd{set print frame-arguments} in @ref{Print Settings} for more details
+on how to configure the way function parameter values are printed.
+
 @cindex value optimized out, in backtrace
 @cindex function call arguments, optimized out
 If your program was compiled with optimizations, some compilers will
@@ -6984,12 +6991,13 @@ values are:
 
 @table @code
 @item all
-The values of all arguments are printed.  This is the default.
+The values of all arguments are printed.
 
 @item scalars
 Print the value of an argument only if it is a scalar.  The value of more
 complex arguments such as arrays, structures, unions, etc, is replaced
-by @code{@dots{}}.  Here is an example where only scalar arguments are shown:
+by @code{@dots{}}.  This is the default.  Here is an example where
+only scalar arguments are shown:
 
 @smallexample
 #1  0x08048361 in call_me (i=3, s=@dots{}, ss=0xbf8d508c, u=@dots{}, e=green)
@@ -7006,14 +7014,16 @@ is replaced by @code{@dots{}}.  In this case, the example above now becomes:
 @end smallexample
 @end table
 
-By default, all argument values are always printed.  But this command
-can be useful in several cases.  For instance, it can be used to reduce
-the amount of information printed in each frame, making the backtrace
-more readable.  Also, this command can be used to improve performance
-when displaying Ada frames, because the computation of large arguments
-can sometimes be CPU-intensive, especiallly in large applications.
-Setting @code{print frame-arguments} to @code{scalars} or @code{none}
-avoids this computation, thus speeding up the display of each Ada frame.
+By default, only scalar arguments are printed.  This command can be used
+to configure the debugger to print the value of all arguments, regardless
+of their type.  However, it is often advantageous to not print the value
+of more complex parameters.  For instance, it reduces the amount of
+information printed in each frame, making the backtrace more readable.
+Also, it improves performance when displaying Ada frames, because
+the computation of large arguments can sometimes be CPU-intensive,
+especially in large applications.  Setting @code{print frame-arguments}
+to @code{scalars} (the default) or @code{none} avoids this computation,
+thus speeding up the display of each Ada frame.
 
 @item show print frame-arguments
 Show how the value of arguments should be displayed when printing a frame.