gdb/doc: update syntax of -data-disassemble command arguments
authorAndrew Burgess <aburgess@redhat.com>
Thu, 23 Jun 2022 12:57:57 +0000 (13:57 +0100)
committerAndrew Burgess <aburgess@redhat.com>
Sun, 2 Oct 2022 10:58:28 +0000 (11:58 +0100)
commit48883ade64759b72aa876d6255796c8e66429be8
treef0a8d45471f7693ddab5b62a8020bd250809704c
parent2bfed4e87257a8d6433edb145326da31816d19c1
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.
gdb/doc/gdb.texinfo