Re: [PATCH v2 4/4] Introduce the "with" command

[Eli Zaretskii <eliz at gnu dot org>]

> 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.

> +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.

> +  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?

The documentation parts are OK with these nits fixed.

Thanks.