[PATCH 7/9] gdb/doc: update syntax of -data-disassemble command arguments

[Andrew Burgess]

Eli Zaretskii via Gdb-patches <gdb-patches@sourceware.org> writes:

>> Date: Thu, 23 Jun 2022 17:05:14 +0100
>> From: Andrew Burgess via Gdb-patches <gdb-patches@sourceware.org>
>> Cc: Andrew Burgess <aburgess@redhat.com>
>> 
>> The argument documentation looks like this:
>> 
>>    -data-disassemble
>>       [ -s @var{start-addr} -e @var{end-addr} ]
>>     | [ -a @var{addr} ]
>>     | [ -f @var{filename} -l @var{linenum} [ -n @var{lines} ] ]
>>     -- @var{mode}
>> 
>> However, I believe, according to the 'Notation and Terminology'
>> section, this means that the there are 3 optional location
>> specification argument groups for the command, followed by a
>> non-optional '-- mode'.
>> 
>> However, this is not true, one of the location specification must be
>> given, i.e. we can't choose to give NO location specification, which
>> is what the above implies.
>
> I don't believe we ever used this convention this rigorously.  But I
> agree that it is better to be as accurate as possible.

I agree, and I don't plan to go out of my way to "fix" the syntax of
every command, it was just that with my next patch the syntax became
rather muddled unless we were a little more rigorous.

>
>> I propose that we change this to instead be:
>> 
>>    -data-disassemble
>>     ( -s @var{start-addr} -e @var{end-addr}
>>     | -a @var{addr}
>>     | -f @var{filename} -l @var{linenum} [ -n @var{lines} ] )
>>     -- @var{mode}
>> 
>> By placing all the location specifications within '( ... )' we
>> indication that these are a group, from which one of the options,
>> separated by '|', must be selected.
>
> According to "Notation and Terminology", the (...) construct should be
> followed by either * or +, so I think you should use + here.

You are correct that (...) is not mentioned.  Unfortunately (...)+
clearly means one or more times, and this is not correct in this case.
I propose adding (...) to the "Notation and Terminology" section to mean
exactly once.

How's the patch below?

Thanks,
Andrew

---

commit e151b49f5adac4f42bc5df977c5ab646ef7fe83c
Author: Andrew Burgess <aburgess@redhat.com>
Date:   Thu Jun 23 13:57:57 2022 +0100

    gdb/doc: update syntax of -data-disassemble command arguments
    
    The argument documentation for -data-disassemble looks like this:
    
       -data-disassemble
          [ -s @var{start-addr} -e @var{end-addr} ]
        | [ -a @var{addr} ]
        | [ -f @var{filename} -l @var{linenum} [ -n @var{lines} ] ]
        -- @var{mode}
    
    However, I believe, according to the 'Notation and Terminology'
    section, this means that the there are 3 optional location
    specification argument groups for the command, followed by a
    non-optional '-- mode'.
    
    However, this is not true, one of the location specifications must be
    given, i.e. we can't choose to give NO location specification, which
    is what the above implies.
    
    I propose that we change this to instead be:
    
       -data-disassemble
        ( -s @var{start-addr} -e @var{end-addr}
        | -a @var{addr}
        | -f @var{filename} -l @var{linenum} [ -n @var{lines} ] )
        -- @var{mode}
    
    By placing all the location specifications within '( ... )' we
    indication that these are a group, from which one of the options,
    separated by '|', must be selected.
    
    However, the 'Notation and Terminology' section only describes two
    uses for parenthesis: '( GROUP )*' and '( GROUP )+', in the first case
    GROUP is repeated zero or more times, and in the second GROUP is
    repeated 1 or more times.
    
    Neither of those exactly describe what I want, which is GROUP must
    appear exactly once.  I propose to extend 'Notation and Terminology'
    to include '( GROUP )' which means that GROUP should appear exactly
    once.
    
    This change is important because, in a later commit, I want to add
    additional optional arguments to the -data-disassemble command, and
    things start to get confusing with the original syntax.

diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index 9ae88ee03df..984ad9c1ed1 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -29766,6 +29766,10 @@
 @code{( @var{group} )+} means that @var{group} inside the parentheses
 may repeat one or more times.
 
+@item
+@code{( @var{group} )} means that @var{group} inside the parentheses
+occurs exactly once.
+
 @item
 @code{"@var{string}"} means a literal @var{string}.
 @end itemize
@@ -34416,9 +34420,9 @@
 
 @smallexample
  -data-disassemble
-    [ -s @var{start-addr} -e @var{end-addr} ]
-  | [ -a @var{addr} ]
-  | [ -f @var{filename} -l @var{linenum} [ -n @var{lines} ] ]
+  ( -s @var{start-addr} -e @var{end-addr}
+  | -a @var{addr}
+  | -f @var{filename} -l @var{linenum} [ -n @var{lines} ] )
   -- @var{mode}
 @end smallexample