From: Andrew Burgess <aburgess@redhat.com>
To: Eli Zaretskii <eliz@gnu.org>
Cc: gdb-patches@sourceware.org
Subject: Re: [PATCH 7/9] gdb/doc: update syntax of -data-disassemble command arguments
Date: Thu, 30 Jun 2022 11:18:35 +0100 [thread overview]
Message-ID: <87fsjmcv44.fsf@redhat.com> (raw)
In-Reply-To: <835ykre4fb.fsf@gnu.org>
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
next prev parent reply other threads:[~2022-06-30 10:18 UTC|newest]
Thread overview: 25+ messages / expand[flat|nested] mbox.gz Atom feed top
2022-06-23 16:05 [PATCH 0/9] Disassembler opcode display and text alignment Andrew Burgess
2022-06-23 16:05 ` [PATCH 1/9] gdb/doc: improve description of --data-disassemble opcodes output Andrew Burgess
2022-06-23 16:09 ` Eli Zaretskii
2022-06-29 12:54 ` Andrew Burgess
2022-06-23 16:05 ` [PATCH 2/9] gdb/testsuite: new test for -data-disassemble opcodes format Andrew Burgess
2022-06-23 16:05 ` [PATCH 3/9] gdb/disasm: read opcodes bytes with a single read_code call Andrew Burgess
2022-06-23 16:05 ` [PATCH 4/9] gdb: disassembler opcode display formatting Andrew Burgess
2022-06-23 16:14 ` Eli Zaretskii
2022-06-23 16:05 ` [PATCH 5/9] gdb: make gdb_disassembly_flag unsigned Andrew Burgess
2022-06-23 16:05 ` [PATCH 6/9] gdb/doc: fix column widths in MI compatibility table Andrew Burgess
2022-06-23 16:22 ` Eli Zaretskii
2022-06-30 9:39 ` Andrew Burgess
2022-06-23 16:05 ` [PATCH 7/9] gdb/doc: update syntax of -data-disassemble command arguments Andrew Burgess
2022-06-23 16:21 ` Eli Zaretskii
2022-06-30 10:18 ` Andrew Burgess [this message]
2022-06-30 10:46 ` Eli Zaretskii
2022-06-23 16:05 ` [PATCH 8/9] gdb/mi: some int to bool conversion Andrew Burgess
2022-06-23 16:05 ` [PATCH 9/9] gdb/mi: new options for -data-disassemble command Andrew Burgess
2022-06-23 16:34 ` Eli Zaretskii
2022-06-30 11:22 ` Andrew Burgess
2022-06-30 13:36 ` Eli Zaretskii
2022-07-25 18:28 ` [PATCH 0/9] Disassembler opcode display and text alignment Andrew Burgess
2022-09-05 14:11 ` Andrew Burgess
2022-09-21 16:41 ` Tom Tromey
2022-10-02 13:15 ` Andrew Burgess
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=87fsjmcv44.fsf@redhat.com \
--to=aburgess@redhat.com \
--cc=eliz@gnu.org \
--cc=gdb-patches@sourceware.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).