Re: [PATCHv2 5/5] gdb: Introduce 'print max-depth' feature

[Andrew Burgess <andrew.burgess@embecosm.com>]

* Eli Zaretskii <eliz@gnu.org> [2019-04-18 05:38:11 +0300]:

> > Date: Thu, 18 Apr 2019 02:07:26 +0100
> > From: Andrew Burgess <andrew.burgess@embecosm.com>
> > Cc: gdb-patches@sourceware.org
> > 
> > > "increase ... to increase" sounds awkward and perhaps even confusing.
> > > Can we come up with a better wording?
> > 
> > You're right, that doesn't read well, how about simply dropping the
> > '...to increase' like this:
> > 
> > 
> >     +To see the contents of structures that have been hidden the user
> >     +can either increase the print max-depth, or they can print the
> >     +elements of the structure that are visible, for example
> 
> Fine with me, thanks.

Eli, thanks for the feedback.

Having taken Philippe's feedback on board too, I have now adjusted how
I show the effects of the different depth settings to use a table
instead of a set of paragraphs.

I just wanted to run this by you to make sure I hadn't made any silly
style mistakes.

The diff below is only for gdb/doc/gdb.texinfo - this is the only file
I've changed over the previous version of the patch.

thanks,
Andrew

--

diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index f410d026b82..02e90284494 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -10560,6 +10560,64 @@
 Display the current threshold for printing repeated identical
 elements.
 
+@item set print max-depth @var{depth}
+@item set print max-depth unlimited
+@cindex printing nested structures
+Set the threshold after which nested structures are replaced with
+ellipsis, this can make visualising deeply nested structures easier.
+
+For example, given this C code
+
+@smallexample
+typedef struct s1 @{ int a; @} s1;
+typedef struct s2 @{ s1 b; @} s2;
+typedef struct s3 @{ s2 c; @} s3;
+typedef struct s4 @{ s3 d; @} s4;
+
+s4 var = @{ @{ @{ @{ 3 @} @} @} @};
+@end smallexample
+
+The following table shows how different values of @var{depth} will
+effect how @code{var} is printed by @value{GDBN}:
+
+@multitable @columnfractions .3 .7
+@headitem @var{depth} setting @tab Result of @samp{p var}
+@item unlimited
+@tab @code{$1 = @{d = @{c = @{b = @{a = 3@}@}@}@}}
+@item @code{0}
+@tab @code{$1 = @{...@}}
+@item @code{1}
+@tab @code{$1 = @{d = @{...@}@}}
+@item @code{2}
+@tab @code{$1 = @{d = @{c = @{...@}@}@}}
+@item @code{3}
+@tab @code{$1 = @{d = @{c = @{b = @{...@}@}@}@}}
+@item @code{4}
+@tab @code{$1 = @{d = @{c = @{b = @{a = 3@}@}@}@}}
+@end multitable
+
+To see the contents of structures that have been hidden the user can
+either increase the print max-depth, or they can print the elements of
+the structure that are visible, for example
+
+@smallexample
+(gdb) set print max-depth 2
+(gdb) p var
+$1 = @{d = @{c = @{...@}@}@}
+(gdb) p var.d
+$2 = @{c = @{b = @{...@}@}@}
+(gdb) p var.d.c
+$3 = @{b = @{a = 3@}@}
+@end smallexample
+
+The pattern used to replace nested structures varies based on
+language, for most languages @code{@{...@}} is used, but Fortran uses
+@code{(...)}.
+
+@item show print max-depth
+Display the current threshold after which nested structures are
+replaces with ellipsis.
+
 @item set print null-stop
 @cindex @sc{null} elements in arrays
 Cause @value{GDBN} to stop printing the characters of an array when the first