[PATCH 0/1] Correct argument description for info connections/inferiors

[PATCH 0/1] Correct argument description for info connections/inferiors

[Christina Schimpe]

Hi all,

this patch was originally written by Nils-Christian Kempke.
I just rebased it onto current master.

Regards,
Christina

Nils-Christian Kempke (1):
  gdb, doc: correct argument description for info connections/inferiors

 gdb/doc/gdb.texinfo | 23 ++++++++++++++++-------
 1 file changed, 16 insertions(+), 7 deletions(-)

-- 
2.25.1

Intel Deutschland GmbH
Registered Address: Am Campeon 10, 85579 Neubiberg, Germany
Tel: +49 89 99 8853-0, www.intel.de <http://www.intel.de>
Managing Directors: Christin Eisenschmid, Sharon Heck, Tiffany Doon Silva  
Chairperson of the Supervisory Board: Nicole Lau
Registered Office: Munich
Commercial Register: Amtsgericht Muenchen HRB 186928

[PATCH 1/1] gdb, doc: correct argument description for info connections/inferiors

[Christina Schimpe]

From: Nils-Christian Kempke <nils-christian.kempke@intel.com>

It said for 'info inferiors' and 'info connections' that the argument
could be 'a space separated list of inferior numbers' which is correct
but incomplete.  In fact the arguments can be any space separated
combination of numbers and (ascending) ranges.

The beginning of the section now describes the ID list as a new keyword.

Co-Authored-By: Christina Schimpe <christina.schimpe@intel.com>
---
 gdb/doc/gdb.texinfo | 23 ++++++++++++++++-------
 1 file changed, 16 insertions(+), 7 deletions(-)

diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index 6c811b8be2e..da008e34dfa 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -3216,6 +3216,16 @@ embedded targets may have several inferiors running in different parts
 of a single address space.  Each inferior may in turn have multiple
 threads running in it.
 
+@anchor{ID list}
+@cindex ID list
+The commands @code{info inferiors} and @code{info connections}, which will be
+introduced below, accept a space-separated @dfn{ID list} as their argument
+specifying one or more elements on which to operate.  A list element can be
+either a single non-negative number, like @samp{5}, or an ascending range of
+such numbers, like @samp{5-7}.  A list can consist of any combination of such
+elements, even duplicates or overlapping ranges are valid.  E.g.@:
+@samp{1 4-6 5 4-4} or @samp{1 2 4-7}.
+
 To find out what inferiors exist at any moment, use @w{@code{info
 inferiors}}:
 
@@ -3223,9 +3233,9 @@ inferiors}}:
 @kindex info inferiors [ @var{id}@dots{} ]
 @item info inferiors
 Print a list of all inferiors currently being managed by @value{GDBN}.
-By default all inferiors are printed, but the argument @var{id}@dots{}
--- a space separated list of inferior numbers -- can be used to limit
-the display to just the requested inferiors.
+By default all inferiors are printed, but the ID list (@pxref{ID list})
+@var{id}@dots{} can be used to limit the display to just the requested
+inferiors.
 
 @value{GDBN} displays for each inferior (in this order):
 
@@ -3284,10 +3294,9 @@ To find out what open target connections exist at any moment, use
 @kindex info connections [ @var{id}@dots{} ]
 @item info connections
 Print a list of all open target connections currently being managed by
-@value{GDBN}.  By default all connections are printed, but the
-argument @var{id}@dots{} -- a space separated list of connections
-numbers -- can be used to limit the display to just the requested
-connections.
+@value{GDBN}.  By default all connections are printed, but the ID list
+(@pxref{ID list}) @var{id}@dots{} can be used to limit the display to just the
+requested connections.
 
 @value{GDBN} displays for each connection (in this order):
 
-- 
2.25.1

Intel Deutschland GmbH
Registered Address: Am Campeon 10, 85579 Neubiberg, Germany
Tel: +49 89 99 8853-0, www.intel.de <http://www.intel.de>
Managing Directors: Christin Eisenschmid, Sharon Heck, Tiffany Doon Silva  
Chairperson of the Supervisory Board: Nicole Lau
Registered Office: Munich
Commercial Register: Amtsgericht Muenchen HRB 186928

Re: [PATCH 1/1] gdb, doc: correct argument description for info connections/inferiors

[Eli Zaretskii]

> Cc: Christina Schimpe <christina.schimpe@intel.com>
> Date: Mon, 27 Mar 2023 13:39:22 +0200
> From: Christina Schimpe via Gdb-patches <gdb-patches@sourceware.org>
> 
> From: Nils-Christian Kempke <nils-christian.kempke@intel.com>
> 
> It said for 'info inferiors' and 'info connections' that the argument
> could be 'a space separated list of inferior numbers' which is correct
> but incomplete.  In fact the arguments can be any space separated
> combination of numbers and (ascending) ranges.
> 
> The beginning of the section now describes the ID list as a new keyword.
> 
> Co-Authored-By: Christina Schimpe <christina.schimpe@intel.com>
> ---
>  gdb/doc/gdb.texinfo | 23 ++++++++++++++++-------
>  1 file changed, 16 insertions(+), 7 deletions(-)

Thanks.  The text is OK, but please drop the cross-references (and the
@anchor which you created for them): you actually allude to stuff
described in the same node, and not very far before the referencing
text, so cross-references are inappropriate.  Instead, says "(see
above)", or even nothing at all, since the reader just have read about
ID lists, and there's an index entry for that if the reader forgot.

Reviewed-By: Eli Zaretskii <eliz@gnu.org>

RE: [PATCH 1/1] gdb, doc: correct argument description for info connections/inferiors

[Schimpe, Christina]

Thank you for the review. I will send a v2 soon.

Christina

> -----Original Message-----
> From: Eli Zaretskii <eliz@gnu.org>
> Sent: Monday, March 27, 2023 3:47 PM
> To: Schimpe, Christina <christina.schimpe@intel.com>
> Cc: gdb-patches@sourceware.org
> Subject: Re: [PATCH 1/1] gdb, doc: correct argument description for info
> connections/inferiors
> 
> > Cc: Christina Schimpe <christina.schimpe@intel.com>
> > Date: Mon, 27 Mar 2023 13:39:22 +0200
> > From: Christina Schimpe via Gdb-patches <gdb-patches@sourceware.org>
> >
> > From: Nils-Christian Kempke <nils-christian.kempke@intel.com>
> >
> > It said for 'info inferiors' and 'info connections' that the argument
> > could be 'a space separated list of inferior numbers' which is correct
> > but incomplete.  In fact the arguments can be any space separated
> > combination of numbers and (ascending) ranges.
> >
> > The beginning of the section now describes the ID list as a new keyword.
> >
> > Co-Authored-By: Christina Schimpe <christina.schimpe@intel.com>
> > ---
> >  gdb/doc/gdb.texinfo | 23 ++++++++++++++++-------
> >  1 file changed, 16 insertions(+), 7 deletions(-)
> 
> Thanks.  The text is OK, but please drop the cross-references (and the @anchor
> which you created for them): you actually allude to stuff described in the same
> node, and not very far before the referencing text, so cross-references are
> inappropriate.  Instead, says "(see above)", or even nothing at all, since the
> reader just have read about ID lists, and there's an index entry for that if the
> reader forgot.
> 
> Reviewed-By: Eli Zaretskii <eliz@gnu.org>
Intel Deutschland GmbH
Registered Address: Am Campeon 10, 85579 Neubiberg, Germany
Tel: +49 89 99 8853-0, www.intel.de <http://www.intel.de>
Managing Directors: Christin Eisenschmid, Sharon Heck, Tiffany Doon Silva  
Chairperson of the Supervisory Board: Nicole Lau
Registered Office: Munich
Commercial Register: Amtsgericht Muenchen HRB 186928