[v4,4/4] gdb/doc: document '+' argument for 'list' command

  The command 'list' has accepted the argument '+' for many years already,
but this option wasn't documented either in the texinfo docs or in the
help text for the command.  This commit documents it.

Reviewed-By: Eli Zaretskii <eliz@gnu.org>
---
 gdb/cli/cli-cmds.c  | 1 +
 gdb/doc/gdb.texinfo | 3 +++
 2 files changed, 4 insertions(+)
  

On 7/13/23 03:24, Bruno Larsen via Gdb-patches wrote:

> diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
> index 20c9b24400d..cd86da50f46 100644
> --- a/gdb/doc/gdb.texinfo
> +++ b/gdb/doc/gdb.texinfo
> @@ -9148,6 +9148,9 @@ Stack}), this prints lines centered around that line.  If no
>   @code{list} command has been used and no solitary line was printed,
>   it prints the lines around the function @code{main}.
>   
> +@item list +
> +Same as using with no arguments.
> +
>   @item list -
>   Print lines just before the lines last printed.
>   

Grepping gdb.texinfo for "list +" definitely has a result:

$ grep 'list +' gdb.texinfo
@item list +
list +[NSText initialize]

This is from the same "Printing Source Line" section of the Manual
that your patch touches. This is the blurb which gives a "complete
description of the possible arguments for list".

What your patch does is actually add "list +" to the "most commonly used"
blurb at the top of the section.

I'm not sure I really find that compelling, given that it is essentially
synonymous with just repeating/hitting enter, documented just above it.
To be clear, I am not entirely against it. I'll leave it to the documentation
experts.

[And I see we have a near mid-air collision with an Approved-by. So ignore me!]

Keith
  

On Thu, Jul 13, 2023 at 5:36 PM Keith Seitz via Gdb-patches
<gdb-patches@sourceware.org> wrote:
>
> On 7/13/23 03:24, Bruno Larsen via Gdb-patches wrote:
>
> > diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
> > index 20c9b24400d..cd86da50f46 100644
> > --- a/gdb/doc/gdb.texinfo
> > +++ b/gdb/doc/gdb.texinfo
> > @@ -9148,6 +9148,9 @@ Stack}), this prints lines centered around that line.  If no
> >   @code{list} command has been used and no solitary line was printed,
> >   it prints the lines around the function @code{main}.
> >
> > +@item list +
> > +Same as using with no arguments.
> > +
> >   @item list -
> >   Print lines just before the lines last printed.
> >
>
> Grepping gdb.texinfo for "list +" definitely has a result:
>
> $ grep 'list +' gdb.texinfo
> @item list +
> list +[NSText initialize]
>
> This is from the same "Printing Source Line" section of the Manual
> that your patch touches. This is the blurb which gives a "complete
> description of the possible arguments for list".

I guess it is worth noting that this usage of 'list +[NSText
initialize]', is completely different than the first match '@item list
+' Keith refers to,
it comes from the objective-c section and in that case the '+'
signifies that the initialize method is a class method.
That one comes from the section "Method Names in Commands", an awkward
bit of ambiguity. But it took me a bit to figure out what you
were actually referring to, not seeing the NSText match in that section.

> What your patch does is actually add "list +" to the "most commonly used"
> blurb at the top of the section.
>
> I'm not sure I really find that compelling, given that it is essentially
> synonymous with just repeating/hitting enter, documented just above it.
> To be clear, I am not entirely against it. I'll leave it to the documentation
> experts.
>
> [And I see we have a near mid-air collision with an Approved-by. So ignore me!]
>
> Keith
>
  

On 13/07/2023 23:30, Matt Rice wrote:
> On Thu, Jul 13, 2023 at 5:36 PM Keith Seitz via Gdb-patches
> <gdb-patches@sourceware.org> wrote:
>> On 7/13/23 03:24, Bruno Larsen via Gdb-patches wrote:
>>
>>> diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
>>> index 20c9b24400d..cd86da50f46 100644
>>> --- a/gdb/doc/gdb.texinfo
>>> +++ b/gdb/doc/gdb.texinfo
>>> @@ -9148,6 +9148,9 @@ Stack}), this prints lines centered around that line.  If no
>>>    @code{list} command has been used and no solitary line was printed,
>>>    it prints the lines around the function @code{main}.
>>>
>>> +@item list +
>>> +Same as using with no arguments.
>>> +
>>>    @item list -
>>>    Print lines just before the lines last printed.
>>>
>> Grepping gdb.texinfo for "list +" definitely has a result:
>>
>> $ grep 'list +' gdb.texinfo
>> @item list +
>> list +[NSText initialize]
>>
>> This is from the same "Printing Source Line" section of the Manual
>> that your patch touches. This is the blurb which gives a "complete
>> description of the possible arguments for list".
> I guess it is worth noting that this usage of 'list +[NSText
> initialize]', is completely different than the first match '@item list
> +' Keith refers to,
> it comes from the objective-c section and in that case the '+'
> signifies that the initialize method is a class method.
> That one comes from the section "Method Names in Commands", an awkward
> bit of ambiguity. But it took me a bit to figure out what you
> were actually referring to, not seeing the NSText match in that section.

Yeah, it does sound like some unfortunate bit of ambiguity. I'm sure 
that "list +" is different to "list +[NSText initialize]" because the 
code has a special case for "arg[0] == '+' && arg[1] == '\0'", so it has 
to be a different case.

Would be nice if we could change this to a less ambiguous option, as 
future work...

>
>> What your patch does is actually add "list +" to the "most commonly used"
>> blurb at the top of the section.
>>
>> I'm not sure I really find that compelling, given that it is essentially
>> synonymous with just repeating/hitting enter, documented just above it.
>> To be clear, I am not entirely against it. I'll leave it to the documentation
>> experts.
My reasoning to document it is that all options should be in the 
documentation. If this option is redundant, I think it is a code issue, 
not a documentation issue.
  

>>>>> "Bruno" == Bruno Larsen via Gdb-patches <gdb-patches@sourceware.org> writes:

Bruno> Yeah, it does sound like some unfortunate bit of ambiguity. I'm sure
Bruno> that "list +" is different to "list +[NSText initialize]" because the
Bruno> code has a special case for "arg[0] == '+' && arg[1] == '\0'", so it
Bruno> has to be a different case.

Bruno> Would be nice if we could change this to a less ambiguous option, as
Bruno> future work...

I wonder if the ObjC code even works.  Most of the test cases can't even
be compiled, and no one has maintained it in many years -- I think since
before I worked on gdb.

Tom
  

On Fri, Jul 14, 2023 at 4:30 PM Tom Tromey <tom@tromey.com> wrote:
>
> >>>>> "Bruno" == Bruno Larsen via Gdb-patches <gdb-patches@sourceware.org> writes:
>
> Bruno> Yeah, it does sound like some unfortunate bit of ambiguity. I'm sure
> Bruno> that "list +" is different to "list +[NSText initialize]" because the
> Bruno> code has a special case for "arg[0] == '+' && arg[1] == '\0'", so it
> Bruno> has to be a different case.
>
> Bruno> Would be nice if we could change this to a less ambiguous option, as
> Bruno> future work...
>
> I wonder if the ObjC code even works.  Most of the test cases can't even
> be compiled, and no one has maintained it in many years -- I think since
> before I worked on gdb.
>

Yeah most of the test cases rely upon stuff which the gcc objc runtime
removed and released before I noticed and could object to their
removal
(stuff like removing the Object class following suit from apples
removal of the same things).
At the time I had been working on fixing up and expanding the tests...
A good way forward might be to re-add them to gcc in a separate new
library
That might make it possible to get it working with some past and
future gcc versions.

Without that gdb would have to build it's own runtime for the
testsuite, or rely upon a 3rd party root object in order to test
things like allocating
objects, so we can invoke instance methods... I neither had enough
interest, nor thought it was a good idea for either gdb to maintain
such a thing
or alternately rely upon a external library just for testing...

Because without objects to actually instantiate gdb is pretty limited
in what it can test, and the code for allocating objects from the
runtime is quite runtime dependent.
As such I wouldn't be surprised if it were completely broken either.