From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: by sourceware.org (Postfix, from userid 1726) id 38654385841F; Sun, 2 Oct 2022 13:15:18 +0000 (GMT) DKIM-Filter: OpenDKIM Filter v2.11.0 sourceware.org 38654385841F DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=sourceware.org; s=default; t=1664716518; bh=DpFXWNLd59uBO4ZYnz8OaKRoD6vaJw4/FEMQJPozSaA=; h=From:To:Subject:Date:From; b=na0hsDBLVGsmfD2fSrkZ1yJe8Qyxcvf60RdCkCefSh8fZI0OpwFbcZaS0LFe/zV7B kYHu46fzZSUdzrl17L/wZLznqEs4yIx8KT6m/dZw1vBkEQFn52EGJWcv9NLyw2uMFO o0JoIlofZpH+g9LJNnvoTe+zJ2Bv2s1Mi1nHjLVQ= Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable From: Andrew Burgess To: gdb-cvs@sourceware.org Subject: [binutils-gdb] gdb/doc: update syntax of -data-disassemble command arguments X-Act-Checkin: binutils-gdb X-Git-Author: Andrew Burgess X-Git-Refname: refs/heads/master X-Git-Oldrev: 2bfed4e87257a8d6433edb145326da31816d19c1 X-Git-Newrev: 48883ade64759b72aa876d6255796c8e66429be8 Message-Id: <20221002131518.38654385841F@sourceware.org> Date: Sun, 2 Oct 2022 13:15:18 +0000 (GMT) List-Id: https://sourceware.org/git/gitweb.cgi?p=3Dbinutils-gdb.git;h=3D48883ade6475= 9b72aa876d6255796c8e66429be8 commit 48883ade64759b72aa876d6255796c8e66429be8 Author: Andrew Burgess Date: Thu Jun 23 13:57:57 2022 +0100 gdb/doc: update syntax of -data-disassemble command arguments =20 The argument documentation for -data-disassemble looks like this: =20 -data-disassemble [ -s @var{start-addr} -e @var{end-addr} ] | [ -a @var{addr} ] | [ -f @var{filename} -l @var{linenum} [ -n @var{lines} ] ] -- @var{mode} =20 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'. =20 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. =20 I propose that we change this to instead be: =20 -data-disassemble ( -s @var{start-addr} -e @var{end-addr} | -a @var{addr} | -f @var{filename} -l @var{linenum} [ -n @var{lines} ] ) -- @var{mode} =20 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. =20 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. =20 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. =20 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: --- gdb/doc/gdb.texinfo | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo index 596e5873558..afe29a9a025 100644 --- a/gdb/doc/gdb.texinfo +++ b/gdb/doc/gdb.texinfo @@ -29910,6 +29910,10 @@ may repeat zero or more times. @code{( @var{group} )+} means that @var{group} inside the parentheses may repeat one or more times. =20 +@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 @@ -34580,9 +34584,9 @@ For details about what an addressable memory unit i= s, =20 @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