From patchwork Wed Jun 19 15:46:23 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Pedro Alves X-Patchwork-Id: 33214 Received: (qmail 108026 invoked by alias); 19 Jun 2019 15:46:29 -0000 Mailing-List: contact gdb-patches-help@sourceware.org; run by ezmlm Precedence: bulk List-Id: List-Unsubscribe: List-Subscribe: List-Archive: List-Post: List-Help: , Sender: gdb-patches-owner@sourceware.org Delivered-To: mailing list gdb-patches@sourceware.org Received: (qmail 108017 invoked by uid 89); 19 Jun 2019 15:46:29 -0000 Authentication-Results: sourceware.org; auth=none X-Spam-SWARE-Status: No, score=-26.9 required=5.0 tests=BAYES_00, GIT_PATCH_0, GIT_PATCH_1, GIT_PATCH_2, GIT_PATCH_3, RCVD_IN_DNSWL_NONE autolearn=ham version=3.3.1 spammy=explained, VARIABLE, tweaks, Startup X-HELO: mail-wm1-f67.google.com Received: from mail-wm1-f67.google.com (HELO mail-wm1-f67.google.com) (209.85.128.67) by sourceware.org (qpsmtpd/0.93/v0.84-503-g423c35a) with ESMTP; Wed, 19 Jun 2019 15:46:27 +0000 Received: by mail-wm1-f67.google.com with SMTP id w9so4918951wmd.1 for ; Wed, 19 Jun 2019 08:46:26 -0700 (PDT) Return-Path: Received: from ?IPv6:2001:8a0:f913:f700:56ee:75ff:fe8d:232b? ([2001:8a0:f913:f700:56ee:75ff:fe8d:232b]) by smtp.gmail.com with ESMTPSA id v204sm2294935wma.20.2019.06.19.08.46.24 (version=TLS1_3 cipher=AEAD-AES128-GCM-SHA256 bits=128/128); Wed, 19 Jun 2019 08:46:24 -0700 (PDT) Subject: Re: [PATCH v2 4/4] Introduce the "with" command To: Eli Zaretskii References: <20190618003902.19805-1-palves@redhat.com> <20190618003902.19805-5-palves@redhat.com> <83sgs6sv44.fsf@gnu.org> Cc: gdb-patches@sourceware.org, philippe.waroquiers@skynet.be From: Pedro Alves Message-ID: <3e69e8c9-9025-90ec-e6f6-73e04bd22360@redhat.com> Date: Wed, 19 Jun 2019 16:46:23 +0100 User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:60.0) Gecko/20100101 Thunderbird/60.2.1 MIME-Version: 1.0 In-Reply-To: <83sgs6sv44.fsf@gnu.org> On 6/18/19 5:42 PM, Eli Zaretskii wrote: >> From: Pedro Alves >> Cc: Philippe Waroquiers >> Date: Tue, 18 Jun 2019 01:39:02 +0100 >> >> +@cindex change default behavior of commands >> +@cindex change default settings > > Two index entries that start with the same text and point to the same > place are not useful. I'd drop the second one. I thought it was useful because someone skimming the index might not relate "behavior of commands" to "settings" and vice versa. (settings affect more than commands, like e.g., they change how gdb reacts to inferior events, like forking.) But looking at the resulting page, I have to agree with you, at least the the repetition seems odd. Some settings use a comma to add some kind of context. So how about doing something similar here, like: @cindex change default behavior of commands, settings ? > >> +Many commands change their behavior according to command-specific >> +variables or settings. These settings can be changed with the >> +@code{set} subcommands. For example, the @code{print} command >> +(@pxref{Data, ,Examining Data}) prints arrays differently depending on >> +settings changeable with the commands @code{set print elements >> +NUMBER-OF-ELEMENTS} and @code{set print array-indexes}, among others. >> + >> +You can set these settings to your preference in the gdbinit files >> +loaded at @value{GDBN} startup. @xref{Startup}. >> + >> +The settings can also be changed interactively during the debugging >> +session. For example, to change the limit of array elements to print, >> +you can do the following: >> +@smallexample >> +(@value{GDBN}) set print elements 10 >> +(@value{GDBN}) print some_array >> +$1 = @{0, 10, 20, 30, 40, 50, 60, 70, 80, 90...@} >> +@end smallexample >> + >> +The above @code{set print elements 10} command changes the number of >> +elements to print from the default of 200 to 10. If you only intend >> +this limit of 10 to be used for printing @code{some_array}, then you >> +must restore the limit back to 200, with @code{set print elements >> +200}. >> + >> +Some commands allow overriding settings with command options. For >> +example, the @code{print} command supports a number of options that >> +allow overriding relevant global print settings as set by @code{set >> +print} subcommands. @xref{print options}. The example above could be >> +rewritten as: >> +@smallexample >> +(@value{GDBN}) print -elements 10 -- some_array >> +$1 = @{0, 10, 20, 30, 40, 50, 60, 70, 80, 90...@} >> +@end smallexample >> + >> +Alternatively, you can use the @code{with} command to change a setting >> +temporarily, for the duration of a command invocation. >> + >> +@table @code >> +@kindex with command >> +@kindex w @r{(@code{with})} >> +@cindex settings >> +@cindex temporarily change settings >> +@item with @var{setting} [@var{value}] [-- @var{command}] >> +@itemx w @var{setting} [@var{value}] [-- @var{command}] >> +Temporarily set @var{setting} to @var{value} for the duration of >> +@var{command}. >> + >> +If no @var{command} is provided, the last command executed is >> +repeated. >> + >> +@var{setting} is any setting settable with the @code{set} subcommands. >> + >> +For example, the command >> +@smallexample >> +(@value{GDBN}) with print array on -- print some_array >> +@end smallexample >> +@noindent >> +is equivalent to the following 3 commands: >> +@smallexample >> +(@value{GDBN}) set print array on >> +(@value{GDBN}) print some_array >> +(@value{GDBN}) set print array off >> +@end smallexample >> + >> +The @code{with} command is particularly useful when you want to >> +override a setting while running user-defined commands, or commands >> +defined in Python or Guile. @xref{Extending GDB,, Extending GDB}. >> + >> +@smallexample >> +(@value{GDBN}) with print pretty on -- my_complex_command >> +@end smallexample >> + >> +To change several settings for the same command, you can nest >> +@code{with} commands. For example, @code{with language ada -- with >> +print elements 10} temporarily changes the language to Ada and sets a >> +limit of 10 elements to print for arrays and strings. >> + >> +@end table > > This text is OK, but it keeps absolute silence regarding the "--" > delimiter. It should explain why it is used here and how to use it > with multiple "with" prefixes. I added this where the command's arguments are explained: +If a @var{command} is provided, it must be preceded by a double dash +(@code{--}) separator. This is required because some settings accept +free-form arguments, such as expressions or filenames. As I had mentioned before, it may be we can make this delimiter optional. Also, we may need a "with -separate SEP" option in case someone wants to use an expression with "--" in it. However, I'd rather leave it to a separate pass, as I don't want to spend much more time on this at this point and the need for that should be quite rare. > >> + SETTING is any GDB setting settable with the "set" command. > > "SETTING ... setting settable ... set". How about rewording to use > the root "set" slightly fewer times? Yeah.. I found the repetition just a natural consequence of the nature of the command. The first SETTING is the metavariable name, which has that name because it's the most natural I could find. The last "set" is the name of the "set" command. That leaves the "GDB setting settable" part. But what other name can we give these knobs, other than "GDB settings"? I just referred "knob", but that sounds a bit too informal. I've seen them being called "variables", but that is ambiguous with program variables, and unlike the "set" command, with "set VARIABLE = EXPRESSION", the "with" command does not work with program variables, only GDB settings. And then, what verb to use to refer to tweaking a setting? We're using "change" in some spots, including the cindex discussed above, is that a better choice here? Like: SETTING is any GDB setting changeable with the "set" command. Do you have a better suggestion? > > The documentation parts are OK with these nits fixed. > > Thanks. > I noticed now that I hadn't documented the @var{value} argument, so I fixed it too. These are the tweaks that I currently have locally. Note this fixes NEWS and help along the same lines too. From f235d6b5a28594ddd481d36976a8fa7c6ff65062 Mon Sep 17 00:00:00 2001 From: Pedro Alves Date: Wed, 19 Jun 2019 16:00:14 +0100 Subject: [PATCH] fix-docs --- gdb/doc/gdb.texinfo | 11 ++++++++--- gdb/NEWS | 4 ++-- gdb/cli/cli-cmds.c | 2 +- gdb/maint.c | 2 +- 4 files changed, 12 insertions(+), 7 deletions(-) diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo index 635bcff46e1..c9933af8cc8 100644 --- a/gdb/doc/gdb.texinfo +++ b/gdb/doc/gdb.texinfo @@ -1620,8 +1620,7 @@ for editing. @node Command Settings @section Command Settings -@cindex change default behavior of commands -@cindex change default settings +@cindex change default behavior of commands, settings Many commands change their behavior according to command-specific variables or settings. These settings can be changed with the @@ -1671,10 +1670,16 @@ temporarily, for the duration of a command invocation. Temporarily set @var{setting} to @var{value} for the duration of @var{command}. +@var{setting} is any setting changeable with the @code{set} +subcommands. @var{value} is the value the setting is changed to while +the command is run. + If no @var{command} is provided, the last command executed is repeated. -@var{setting} is any setting settable with the @code{set} subcommands. +If a @var{command} is provided, it must be preceded by a double dash +(@code{--}) separator. This is required because some settings accept +free-form arguments, such as expressions or filenames. For example, the command @smallexample diff --git a/gdb/NEWS b/gdb/NEWS index 850ab44df3c..dc4b0012919 100644 --- a/gdb/NEWS +++ b/gdb/NEWS @@ -51,7 +51,7 @@ w SETTING [VALUE] [-- COMMAND] Temporarily set SETTING, run COMMAND, and restore SETTING. Usage: with SETTING -- COMMAND With no COMMAND, repeats the last executed command. - SETTING is any GDB setting settable with the "set" command. + SETTING is any GDB setting changeable with the "set" subcommands. For example, 'with language c -- print someobj' temporarily switches to the C language in order to print someobj. Settings can be combined: 'w lang c -- w print elements unlimited -- usercmd' @@ -59,7 +59,7 @@ w SETTING [VALUE] [-- COMMAND] elements to print. maint with SETTING [VALUE] [-- COMMAND] - Like "with", but works with "maintenance set" variables. + Like "with", but works with "maintenance set" settings. set may-call-functions [on|off] show may-call-functions diff --git a/gdb/cli/cli-cmds.c b/gdb/cli/cli-cmds.c index 283bc446026..5a88c9f3c1b 100644 --- a/gdb/cli/cli-cmds.c +++ b/gdb/cli/cli-cmds.c @@ -1959,7 +1959,7 @@ Temporarily set SETTING to VALUE, run COMMAND, and restore SETTING.\n\ Usage: with SETTING [VALUE] [-- COMMAND]\n\ Usage: w SETTING [VALUE] [-- COMMAND]\n\ With no COMMAND, repeats the last executed command.\n\ -SETTING is any setting settable with the \"set\" subcommands.\n\ +SETTING is any setting changeable with the \"set\" subcommands.\n\ E.g.:\n\ with language pascal -- print obj\n\ with print elements unlimited -- print obj")); diff --git a/gdb/maint.c b/gdb/maint.c index 2c10903539b..4e93583b806 100644 --- a/gdb/maint.c +++ b/gdb/maint.c @@ -1046,7 +1046,7 @@ Configure variables internal to GDB that aid in GDB's maintenance"), Like \"with\", but works with \"maintenance set\" variables.\n\ Usage: maintenance with SETTING [VALUE] [-- COMMAND]\n\ With no COMMAND, repeats the last executed command.\n\ -SETTING is any setting settable with the \"maintenance set\" subcommands."), +SETTING is any setting changeable with the \"maintenance set\" subcommands."), &maintenancelist); set_cmd_completer_handle_brkchars (cmd, maintenance_with_cmd_completer);