Re: [PATCH 01/12] Document conventions for describing packet syntax

[Pedro Alves <pedro@palves.net>]

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>
>