Re: [patch/doc] Tweak "info inferiors" output.

[Pedro Alves <pedro@codesourcery.com>]

On Friday 14 August 2009 21:13:24, Eli Zaretskii wrote:
> > From: Pedro Alves <pedro@codesourcery.com>
> > Date: Fri, 14 Aug 2009 20:15:59 +0100
> > 
> > >   . Does "ID" and the numbers below it really fail to align, as the
> > >     example shows?  If so, perhaps we should align them.
> > 
> > It's a single column called "Target ID".  The target can put there
> > whatever it wants, though "process foo" will be the most common.
> 
> Then I suggest to drop the "ID" part and just say "Target".  Or maybe
> "Inferior", this being "info inferiors".

"Target", me don't likes.  "Inferior", hmm, maybe that's good.  Before
I change that, if we were to add column headers to "info threads", what
would we call it's second column?  This is really the same thing
applied to inferiors.

Here's what the docs say when describing "info threads":

@item
the target system's inferior identifier (@var{systag})
@end enumerate

@var{systag} is then mentioned in several other places
where that string can appear.  I think we'll want to do
the same for cases where we will print the inferior's
target system's ID (--- we're going to add more of
those for sure).

> 
> > (gdb) info inferiors
> >   Id   Target ID
> > * 1    process 309954
> >   4    capsule 2342
> >   2    process 109
> >   3    process 56
> >   5    foo 1234
> >   6    remote target
> 
> What can appear there beyond "process NNN" and "remote rarget"?  Are
> the other examples above real or just hypothetical?

Whatever appears there is the result of a target_pid_to_str call, just
like the second column in "info threads".  Currently, the others are
hypothetical, but I can see us adding a few more.  E.g, remote-sim
would likely print something different, and you may want (or not) to 
hide the magic 42 used by go32-nat.c.

> For processes, I'd prefer "process (PID NNN)".  

Hmm, not sure.  The data in parentheses looks like
something that isn't mandatory to be displayed, just
something extra when there's row space for it.  But, just "process"
doesn't make sense here.

> Just "process NNN" is 
> not enough to unequivocally indicate what the number is, IMO.

That's how we've printed a process id forever.  It's just
target_pid_to_str -> normal_pid_to_str.

> 
> > The target decides what to print here.
> 
> Well, I rather hope that the programmer, i.e. the GDB developers,
> decide what to print there ;-)

Eh. :-)  By target I meant the target_ops.

> 
> > >   . I'd prefer to explain what can appear under "Target".
> > 
> > Okay, I can do that.

I've looked at the description of "info threads", and carried
over.  While doing so, I've noticed that we should be calling
GDB inferior numbers "Numbers", not "IDs".  "info breakpoints"
also calls the first column "Num".

What do you think of this one?  We just need to settle on the
column name, I think.

-- 
Pedro Alves

2009-08-14  Pedro Alves  <pedro@codesourcery.com>

	* inferior.c (print_inferior): Align columns left.  Remove header
	for the the "current" column.  Rename column "Id" to "Num".
	Rename column "PID" to "Target ID".  Print if there's no selected
	inferior.

2009-08-14  Pedro Alves  <pedro@codesourcery.com>

	* gdb.texinfo (Debugging Multiple Inferiors): Add "info inferiors"
	small example, and describe its columns.  Replace "inferior-id" by
	"infno" throughout.

---
 gdb/doc/gdb.texinfo |   47 +++++++++++++++++++++++++++++++++++------------
 gdb/inferior.c      |   16 +++++++++++-----
 2 files changed, 46 insertions(+), 17 deletions(-)

Index: src/gdb/inferior.c
===================================================================
--- src.orig/gdb/inferior.c	2009-08-14 18:39:17.000000000 +0100
+++ src/gdb/inferior.c	2009-08-17 15:17:03.000000000 +0100
@@ -324,9 +324,9 @@ print_inferior (struct ui_out *uiout, in
 
   old_chain = make_cleanup_ui_out_table_begin_end (uiout, 3, inf_count,
 						   "inferiors");
-  ui_out_table_header (uiout, 3, ui_right, "current", "Cur");
-  ui_out_table_header (uiout, 4, ui_right, "id", "Id");
-  ui_out_table_header (uiout, 7, ui_right, "target-id", "PID");
+  ui_out_table_header (uiout, 1, ui_left, "current", "");
+  ui_out_table_header (uiout, 4, ui_left, "number", "Num");
+  ui_out_table_header (uiout, 17, ui_left, "target-id", "Target ID");
   ui_out_table_body (uiout);
 
   for (inf = inferior_list; inf; inf = inf->next)
@@ -343,13 +343,19 @@ print_inferior (struct ui_out *uiout, in
       else
 	ui_out_field_skip (uiout, "current");
 
-      ui_out_field_int (uiout, "id", inf->num);
-      ui_out_field_int (uiout, "target-id", inf->pid);
+      ui_out_field_int (uiout, "number", inf->num);
+      ui_out_field_string (uiout, "target-id",
+			   target_pid_to_str (pid_to_ptid (inf->pid)));
 
       ui_out_text (uiout, "\n");
       do_cleanups (chain2);
     }
 
+  if (inferior_list
+      && ptid_equal (inferior_ptid, null_ptid))
+    ui_out_message (uiout, 0, "\n\
+No selected inferior/thread.  See `help thread' or `help inferior'.\n");
+
   do_cleanups (old_chain);
 }
 
Index: src/gdb/doc/gdb.texinfo
===================================================================
--- src.orig/gdb/doc/gdb.texinfo	2009-08-14 18:39:17.000000000 +0100
+++ src/gdb/doc/gdb.texinfo	2009-08-17 15:15:02.000000000 +0100
@@ -2374,17 +2374,40 @@ To find out what inferiors exist at any 
 @kindex info inferiors
 @item info inferiors
 Print a list of all inferiors currently being managed by @value{GDBN}.
+
+@value{GDBN} displays for each inferior (in this order):
+
+@enumerate
+@item
+the inferior number assigned by @value{GDBN}
+
+@item
+the target system's inferior identifier (@var{systag})
+@end enumerate
+
+@noindent
+An asterisk @samp{*} to the left of the @value{GDBN} inferior number
+indicates the current inferior.
+
+For example,
 @end table
+@c end table here to get a little more width for example
+
+@smallexample
+(@value{GDBP}) info inferiors
+  Num  Target ID
+* 1    process 2307
+  2    process 3401
+@end smallexample
 
 To switch focus between inferiors, use the @code{inferior} command:
 
 @table @code
-@kindex inferior @var{inferior-id}
-@item inferior @var{inferior-id}
-Make inferior number @var{inferior-id} the current inferior.  The
-argument @var{inferior-id} is the internal inferior number assigned by
-@value{GDBN}, as shown in the first field of the @samp{info inferiors}
-display.
+@kindex inferior @var{infno}
+@item inferior @var{infno}
+Make inferior number @var{infno} the current inferior.  The argument
+@var{infno} is the inferior number assigned by @value{GDBN}, as shown
+in the first field of the @samp{info inferiors} display.
 @end table
 
 To quit debugging one of the inferiors, you can either detach from it
@@ -2392,15 +2415,15 @@ by using the @w{@code{detach inferior}} 
 independently), or kill it using the @w{@code{kill inferior}} command:
 
 @table @code
-@kindex detach inferior @var{inferior-id}
-@item detach inferior @var{inferior-id}
+@kindex detach inferior @var{infno}
+@item detach inferior @var{infno}
 Detach from the inferior identified by @value{GDBN} inferior number
-@var{inferior-id}, and remove it from the inferior list.
+@var{infno}, and remove it from the inferior list.
 
-@kindex kill inferior @var{inferior-id}
-@item kill inferior @var{inferior-id}
+@kindex kill inferior @var{infno}
+@item kill inferior @var{infno}
 Kill the inferior identified by @value{GDBN} inferior number
-@var{inferior-id}, and remove it from the inferior list.
+@var{infno}, and remove it from the inferior list.
 @end table
 
 To be notified when inferiors are started or exit under @value{GDBN}'s