From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from simark.ca by simark.ca with LMTP id VemYNJZ4vWJMZwkAWB0awg (envelope-from ) for ; Thu, 30 Jun 2022 06:19:02 -0400 Received: by simark.ca (Postfix, from userid 112) id C28421E22B; Thu, 30 Jun 2022 06:19:02 -0400 (EDT) Authentication-Results: simark.ca; dkim=pass (1024-bit key; secure) header.d=sourceware.org header.i=@sourceware.org header.a=rsa-sha256 header.s=default header.b=uGmipWtI; dkim-atps=neutral X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on simark.ca X-Spam-Level: X-Spam-Status: No, score=-2.0 required=5.0 tests=BAYES_00,DKIM_SIGNED, DKIM_VALID,DKIM_VALID_AU,MAILING_LIST_MULTI,RDNS_DYNAMIC,URIBL_BLOCKED autolearn=ham autolearn_force=no version=3.4.6 Received: from sourceware.org (ip-8-43-85-97.sourceware.org [8.43.85.97]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256) (No client certificate requested) by simark.ca (Postfix) with ESMTPS id 2AC351E227 for ; Thu, 30 Jun 2022 06:19:02 -0400 (EDT) Received: from server2.sourceware.org (localhost [IPv6:::1]) by sourceware.org (Postfix) with ESMTP id DD3233842AC4 for ; Thu, 30 Jun 2022 10:19:00 +0000 (GMT) DKIM-Filter: OpenDKIM Filter v2.11.0 sourceware.org DD3233842AC4 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=sourceware.org; s=default; t=1656584340; bh=8IVs6XkjY6sBs7xiCZGZqRtLkoSEu+xhf+R8alrWYp4=; h=To:Subject:In-Reply-To:References:Date:List-Id:List-Unsubscribe: List-Archive:List-Post:List-Help:List-Subscribe:From:Reply-To:Cc: From; b=uGmipWtI7fTevetXjF1yedKJ8T/2tLZEuOvhfqqLpuC/O4v99P2wlwMR9y2YE4oXA lsKu0zudo/wb+N2yLaSJ9YRc+HC7kwpeMzzllv4+zEbCWe1wPrrssC9XkcRsRs47O4 QpHB1R/tgt/HCDqKR5l/S7ZYOY7fbCbg0YUJeenk= 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) To: Eli Zaretskii 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-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: , From: Andrew Burgess via Gdb-patches Reply-To: Andrew Burgess Cc: gdb-patches@sourceware.org Errors-To: gdb-patches-bounces+public-inbox=simark.ca@sourceware.org Sender: "Gdb-patches" 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