[PATCH 01/12] Document conventions for describing packet syntax
Pedro Alves
pedro@palves.net
Mon Apr 22 19:01:17 GMT 2024
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>
>
More information about the Gdb-patches
mailing list