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

[Bruno Larsen]

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.

-- 
Cheers,
Bruno

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