[01/12] Document conventions for describing packet syntax

  This comment documents conventions for describing packet syntax in the
Overview section.

Change-Id: I96198592601b24c983da563d143666137e4d0a4e
Co-Authored-By: Jim Blandy <jimb@codesourcery.com>
Co-Authored-By: Mike Wrighton <mike_wrighton@mentor.com>
Co-Authored-By: Nathan Sidwell <nathan@codesourcery.com>
Co-Authored-By: Hafiz Abid Qadeer <abidh@codesourcery.com>
---
 gdb/doc/gdb.texinfo | 16 ++++++++++++++++
 1 file changed, 16 insertions(+)
  

> From: Pedro Alves <pedro@palves.net>
> Cc: Jim Blandy <jimb@codesourcery.com>,
>  Mike Wrighton <mike_wrighton@mentor.com>,
>  Nathan Sidwell <nathan@codesourcery.com>,
>  Hafiz Abid Qadeer <abidh@codesourcery.com>
> Date: Fri, 19 Apr 2024 16:13:31 +0100
> 
> This comment documents conventions for describing packet syntax in the
> Overview section.

Thanks.

> +We place optional portions of a packet in @r{[}square brackets@r{]};

This should be in @samp, otherwise the @r parts are redundant and
won't have any effect.

> +for example, a template like @samp{c @r{[}@var{addr}@r{]}} describes a
> +packet beginning with the single ASCII character @samp{c}, possibly
> +followed by an @var{addr}.

OK with this nit fixed.

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

> Date: Fri, 19 Apr 2024 18:25:26 +0300
> From: Eli Zaretskii <eliz@gnu.org>
> Cc: gdb-patches@sourceware.org, jimb@codesourcery.com,
>  mike_wrighton@mentor.com, nathan@codesourcery.com, abidh@codesourcery.com
> 
> > From: Pedro Alves <pedro@palves.net>
> > Cc: Jim Blandy <jimb@codesourcery.com>,
> >  Mike Wrighton <mike_wrighton@mentor.com>,
> >  Nathan Sidwell <nathan@codesourcery.com>,
> >  Hafiz Abid Qadeer <abidh@codesourcery.com>
> > Date: Fri, 19 Apr 2024 16:13:31 +0100
> > 
> > This comment documents conventions for describing packet syntax in the
> > Overview section.
> 
> Thanks.

Btw, this response bounced from all the addresses except yours and
gdb-patches.
  

Hi!

On 2024-04-19 16:25, Eli Zaretskii wrote:
>> From: Pedro Alves <pedro@palves.net>
>> Cc: Jim Blandy <jimb@codesourcery.com>,
>>  Mike Wrighton <mike_wrighton@mentor.com>,
>>  Nathan Sidwell <nathan@codesourcery.com>,
>>  Hafiz Abid Qadeer <abidh@codesourcery.com>
>> Date: Fri, 19 Apr 2024 16:13:31 +0100
>>
>> This comment documents conventions for describing packet syntax in the
>> Overview section.
> 
> Thanks.
> 
>> +We place optional portions of a packet in @r{[}square brackets@r{]};
> 
> This should be in @samp, otherwise the @r parts are redundant and
> won't have any effect.
> 

Hmm, if I wrap that in @samp, then it renders as:

 We place optional portions of a packet in '[square brackets]'; for example, a template like ‘c [addr]’ describes a packet beginning with the single ASCII character ‘c’, possibly followed by an addr. 

Those '' around [square brackets] seem off to me there.  The original author must have wanted the
rendered text without the single quotes too, since they didn't use @samp and they certainly
looked at the rendered output back then.  So given @r are nops, I think we should just remove them.

That results in:

 We place optional portions of a packet in [square brackets]; for example, a template like ‘c [addr]’ describes a packet beginning with the single ASCII character ‘c’, possibly followed by an addr. 

which IMHO looks better.

If you dislike that, I noticed that:

 https://www.gnu.org/software/texinfo/manual/texinfo/html_node/Command-List.html

says:

 Square brackets, [ ], indicate optional arguments

We could switch to a similar wording.  I kind of like the original better, but
this is a very tiny detail, of course.

Let me know what you think.

Pedro Alves

>> +for example, a template like @samp{c @r{[}@var{addr}@r{]}} describes a
>> +packet beginning with the single ASCII character @samp{c}, possibly
>> +followed by an @var{addr}.
> 
> OK with this nit fixed.
> 
> Approved-By: Eli Zaretskii <eliz@gnu.org>
>
  

On 2024-04-19 16:42, Eli Zaretskii wrote:
>> Date: Fri, 19 Apr 2024 18:25:26 +0300
>> From: Eli Zaretskii <eliz@gnu.org>
>> Cc: gdb-patches@sourceware.org, jimb@codesourcery.com,
>>  mike_wrighton@mentor.com, nathan@codesourcery.com, abidh@codesourcery.com
>>
>>> From: Pedro Alves <pedro@palves.net>
>>> Cc: Jim Blandy <jimb@codesourcery.com>,
>>>  Mike Wrighton <mike_wrighton@mentor.com>,
>>>  Nathan Sidwell <nathan@codesourcery.com>,
>>>  Hafiz Abid Qadeer <abidh@codesourcery.com>
>>> Date: Fri, 19 Apr 2024 16:13:31 +0100
>>>
>>> This comment documents conventions for describing packet syntax in the
>>> Overview section.
>>
>> Thanks.
> 
> Btw, this response bounced from all the addresses except yours and
> gdb-patches.
> 

Right, sorry.  The original patch was from 2007-06-13, and all those inboxes
don't exist any more.  I have:

[sendemail]
        suppresscc = author

in my .gitconfig, and I thought that that would be sufficient for git to not
auto-add the co-authors to CC automatically.  Looks like I was wrong, or I did
something else wrong.
  

> Date: Mon, 22 Apr 2024 20:01:17 +0100
> Cc: gdb-patches@sourceware.org, jimb@codesourcery.com,
>  mike_wrighton@mentor.com, nathan@codesourcery.com, abidh@codesourcery.com
> From: Pedro Alves <pedro@palves.net>
> 
> >> +We place optional portions of a packet in @r{[}square brackets@r{]};
> > 
> > This should be in @samp, otherwise the @r parts are redundant and
> > won't have any effect.
> > 
> 
> Hmm, if I wrap that in @samp, then it renders as:
> 
>  We place optional portions of a packet in '[square brackets]'; for example, a template like ‘c [addr]’ describes a packet beginning with the single ASCII character ‘c’, possibly followed by an addr. 
> 
> Those '' around [square brackets] seem off to me there.  The original author must have wanted the
> rendered text without the single quotes too, since they didn't use @samp and they certainly
> looked at the rendered output back then.  So given @r are nops, I think we should just remove them.

Removing @r is fine by me, thanks.