From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [170.10.129.124]) by sourceware.org (Postfix) with ESMTPS id BBD72386DC51 for ; Thu, 30 Jun 2022 10:18:40 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.1 sourceware.org BBD72386DC51 Received: from mail-wr1-f71.google.com (mail-wr1-f71.google.com [209.85.221.71]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id us-mta-339-3l_DUSvKPYiIajwPUrIUDw-1; Thu, 30 Jun 2022 06:18:39 -0400 X-MC-Unique: 3l_DUSvKPYiIajwPUrIUDw-1 Received: by mail-wr1-f71.google.com with SMTP id z11-20020a056000110b00b0021b9c009d09so3006753wrw.17 for ; Thu, 30 Jun 2022 03:18:38 -0700 (PDT) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=x-gm-message-state:from:to:cc:subject:in-reply-to:references:date :message-id:mime-version; bh=8IVs6XkjY6sBs7xiCZGZqRtLkoSEu+xhf+R8alrWYp4=; b=c6ieRTxVnSgM2YEkFfEnW/X4LhcNR4rEQ1AvtDHppRDCLn5q7bnAPzFHWB00mKQNru m4j78t8eKq2uxzmvDpzLLuXKqJpbtAF2ZLt5xkwpagWD+h9I0/G8pNuHcRwAhSxk+7q0 Mw+8AgplR9fK6F5lFGwCzygJkJJrl81p+KS8Ocv5aE3q1XqA360l8pfLGf6KxbUdeTVf r/eSev+RVjwCyuWnaP075U0/ej+8eAnGlNHebX+pB8FAe8i77/DYII95ejx5ePnNJ+bh Zj/lR8OsYt2EJ+dPxevoIKsHUwoeuPX34eFxE8tEuAhM4SYC+hzOvielQlnt9WFIFEWj YUew== X-Gm-Message-State: AJIora9o6nCZY5+MpLp2+QsPJmQBI/ApjxzveJg7K7y9oqtU4q2pthz8 I/PFGYoEL9dgsZYiiHxkeHK/rm3d1TkFnI6/4YHm8rBewqVjr+Jj4MK6NZrWN+GTndL92ekc+ic sM9TpALMseqDqiUWgMzwStQ== X-Received: by 2002:a5d:64ad:0:b0:21b:a83a:e5ce with SMTP id m13-20020a5d64ad000000b0021ba83ae5cemr7559316wrp.701.1656584317639; Thu, 30 Jun 2022 03:18:37 -0700 (PDT) X-Google-Smtp-Source: AGRyM1tBeOWmET/AoJDnaBogEPKaqgARL0MaxSq4haq1/kDo0xVOOhfnUVRy1CxBJHZ1HuRt5acrhw== X-Received: by 2002:a5d:64ad:0:b0:21b:a83a:e5ce with SMTP id m13-20020a5d64ad000000b0021ba83ae5cemr7559294wrp.701.1656584317374; Thu, 30 Jun 2022 03:18:37 -0700 (PDT) Received: from localhost (15.72.115.87.dyn.plus.net. [87.115.72.15]) by smtp.gmail.com with ESMTPSA id c3-20020adfef43000000b0021bab0ba755sm19740447wrp.106.2022.06.30.03.18.36 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 30 Jun 2022 03:18:36 -0700 (PDT) From: Andrew Burgess To: Eli Zaretskii Cc: gdb-patches@sourceware.org Subject: Re: [PATCH 7/9] gdb/doc: update syntax of -data-disassemble command arguments In-Reply-To: <835ykre4fb.fsf@gnu.org> References: <835ykre4fb.fsf@gnu.org> Date: Thu, 30 Jun 2022 11:18:35 +0100 Message-ID: <87fsjmcv44.fsf@redhat.com> MIME-Version: 1.0 X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Type: text/plain X-Spam-Status: No, score=-10.7 required=5.0 tests=BAYES_00, DKIMWL_WL_HIGH, DKIM_SIGNED, DKIM_VALID, DKIM_VALID_AU, DKIM_VALID_EF, GIT_PATCH_0, RCVD_IN_BARRACUDACENTRAL, RCVD_IN_DNSWL_LOW, SPF_HELO_NONE, SPF_NONE, TXREP, T_SCC_BODY_TEXT_LINE autolearn=ham autolearn_force=no version=3.4.6 X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on server2.sourceware.org X-BeenThere: gdb-patches@sourceware.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: Gdb-patches mailing list List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Thu, 30 Jun 2022 10:18:42 -0000 Eli Zaretskii via Gdb-patches writes: >> Date: Thu, 23 Jun 2022 17:05:14 +0100 >> From: Andrew Burgess via Gdb-patches >> Cc: Andrew Burgess >> >> 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 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