[v2,4/4] Introduce the "with" command

From: Pedro Alves <palves@redhat.com>

  On 6/18/19 5:42 PM, Eli Zaretskii wrote:
>> From: Pedro Alves <palves@redhat.com>
>> Cc: Philippe Waroquiers <philippe.waroquiers@skynet.be>
>> 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 <palves@redhat.com>
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(-)

[v2,4/4] Introduce the "with" command

Commit Message

Comments

Patch