[RFA,3/3] NEWS and documentation for / (slash) command.

Message ID 20190413190016.11970-4-philippe.waroquiers@skynet.be
State New, archived
Headers

Commit Message

Philippe Waroquiers April 13, 2019, 7 p.m. UTC
  gdb/ChangeLog
2019-04-13  Philippe Waroquiers  <philippe.waroquiers@skynet.be>

	* NEWS: Mention new slash command.

gdb/doc/ChangeLog
2019-04-13  Philippe Waroquiers  <philippe.waroquiers@skynet.be>

	* gdb.texinfo (Command Settings): New node documenting
	the general concept of settings, how to change them, and the
	new / command.
---
 gdb/NEWS            |  14 +++++
 gdb/doc/gdb.texinfo | 132 ++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 146 insertions(+)
  

Comments

Eli Zaretskii April 13, 2019, 7:10 p.m. UTC | #1
> From: Philippe Waroquiers <philippe.waroquiers@skynet.be>
> Cc: Philippe Waroquiers <philippe.waroquiers@skynet.be>
> Date: Sat, 13 Apr 2019 21:00:16 +0200
> 
> +* New commands
> +
> +/SETTING... COMMAND
> +  The / command temporarily changes some settings according to SETTING
> +  to run COMMAND.
     ^^^^^^^^^^^^^^
I'd say "for the duration of COMMAND" instead.

> +@cindex Settings
> +@cindex Temporarily change settings

By convention, index entries are not capitalized, to avoid problems
with sorting them alphabetically (which produces locale-dependent
results).

> +The following table gives the list of settings that the @code{/} command
> +can temporarily change.  The first column gives the letter sequence
> +identifying the setting corresponding to the command in the second column.
> +The third column gives the type of the setting, and list the different
> +possible values for the enumeration settings.  Note that the below table
> +is produced by the @code{help /} command.
> +
> +@smallexample
> +@c In the 'doc' build directory, the following can be produced by:
> +@c ../../gdb/gdb -q --nx  -ex 'set width 80' -ex 'set height 0' -ex 'help /' -ex quit |
> +@c   sed -e '1,/The temporarily changeable settings are:/d' -e ':a;s/^\( *\) /@\1/;ta' -e 's/^/@exdent /'
> +@c Maybe this could/should be automated by the doc Makefile ?
> +@exdent /Be       set backtrace past-entry       Boolean on|off
> +@exdent /Bl       set backtrace limit            Unsigned integer (0 means unlimited)

Please rewrite this as a @multitable, so that it looks good in all
formats.

Thanks.
  
Philippe Waroquiers April 13, 2019, 7:22 p.m. UTC | #2
Thanks for the review and the (as usual) good
suggestions/comments.
I will handle them for the next version.

Note that (if not done yet), it might be good
to check the on-line 'help /' doc which is in the top.c file
(see [RFA 1/3]).

Thanks

Philippe

On Sat, 2019-04-13 at 22:10 +0300, Eli Zaretskii wrote:
> > From: Philippe Waroquiers <philippe.waroquiers@skynet.be>
> > Cc: Philippe Waroquiers <philippe.waroquiers@skynet.be>
> > Date: Sat, 13 Apr 2019 21:00:16 +0200
> > 
> > +* New commands
> > +
> > +/SETTING... COMMAND
> > +  The / command temporarily changes some settings according to SETTING
> > +  to run COMMAND.
> 
>      ^^^^^^^^^^^^^^
> I'd say "for the duration of COMMAND" instead.
> 
> > +@cindex Settings
> > +@cindex Temporarily change settings
> 
> By convention, index entries are not capitalized, to avoid problems
> with sorting them alphabetically (which produces locale-dependent
> results).
> 
> > +The following table gives the list of settings that the @code{/} command
> > +can temporarily change.  The first column gives the letter sequence
> > +identifying the setting corresponding to the command in the second column.
> > +The third column gives the type of the setting, and list the different
> > +possible values for the enumeration settings.  Note that the below table
> > +is produced by the @code{help /} command.
> > +
> > +@smallexample
> > +@c In the 'doc' build directory, the following can be produced by:
> > +@c ../../gdb/gdb -q --nx  -ex 'set width 80' -ex 'set height 0' -ex 'help /' -ex quit |
> > +@c   sed -e '1,/The temporarily changeable settings are:/d' -e ':a;s/^\( *\) /@\1/;ta' -e 's/^/@exdent /'
> > +@c Maybe this could/should be automated by the doc Makefile ?
> > +@exdent /Be       set backtrace past-entry       Boolean on|off
> > +@exdent /Bl       set backtrace limit            Unsigned integer (0 means unlimited)
> 
> Please rewrite this as a @multitable, so that it looks good in all
> formats.
> 
> Thanks.
  

Patch

diff --git a/gdb/NEWS b/gdb/NEWS
index 5309a8f923..1ec0418881 100644
--- a/gdb/NEWS
+++ b/gdb/NEWS
@@ -27,6 +27,20 @@ 
      'array_indexes', 'symbols', 'unions', 'deref_refs', 'actual_objects',
      'static_members', 'max_elements', 'repeat_threshold', and 'format'.
 
+* New commands
+
+/SETTING... COMMAND
+  The / command temporarily changes some settings according to SETTING
+  to run COMMAND.  After running COMMAND, the settings are reset to
+  the values they had before the execution.
+  For example, '/lc print somevar' temporarily
+  switches to the C language in order to print somevar.
+  '/r print somevariable' temporarily sets unlimited repeat value
+  to print somevariable.  Settings can be combined: '/rlc print somevar'
+  will switch to the C language and print somevar with an unlimited
+  repeat value.
+  Use 'help /' to list all settings that are temporarily changeable.
+
 *** Changes in GDB 8.3
 
 * GDB and GDBserver now support access to additional registers on
diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index f410d026b8..7521d40036 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -1493,6 +1493,7 @@  show you the alternatives available, if there is more than one possibility).
 
 @menu
 * Command Syntax::              How to give commands to @value{GDBN}
+* Command Settings::            How to change default behaviour of commands
 * Completion::                  Command completion
 * Help::                        How to ask @value{GDBN} for help
 @end menu
@@ -1548,6 +1549,137 @@  commands.  This command accepts the current line, like @key{RET}, and
 then fetches the next line relative to the current line from the history
 for editing.
 
+
+@node Command Settings
+@section Command Settings
+@cindex change default behaviour of commands
+@cindex change default settings
+
+Many commands change their behaviour according to command specific
+variables or settings, that can be changed interactively.
+For example, the @code{print} @pxref{Arguments} command will print arrays
+differently depending on various settings changeable by the commands
+@code{set print elements NUMBER-OF-ELEMENTS},
+@code{set print array-indexes}, @dots{}.
+
+These settings can be set 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,
+the following can be done:
+@smallexample
+(@value{GDBN}) set print elements 10
+print some_array
+$3 = @{0, 10, 20, 30, 40, 50, 60, 70, 80, 90...@}
+@end smallexample
+
+The default value of 200 elements to print has been changed to 10
+by the above @code{set print elements 10} command.  The value of 10
+becomes the new default.  It this value of 10 is to be used only
+for printing @code{some_array}, then the command
+@code{set print elements 200} must be executed to set the default back
+to 200.
+
+@kindex slash command
+@kindex /
+@cindex Settings
+@cindex Temporarily change settings
+@noindent
+@code{/SETTING... COMMAND}: Temporarily change settings for only one command.
+
+The @code{/} (slash) command allows to temporarily change various
+settings to run a specific command.  For example, the command
+@smallexample
+/a10e print some_array
+@end smallexample
+@noindent
+is equivalent to the following 5 commands:
+@smallexample
+set print array on
+set print elements 10
+print some_array
+set print elements 200
+set print array off
+@end smallexample
+
+Each temporarily changeable setting is identified by a sequence of
+one or more letters.  The most frequently used settings are identified
+by a single lower case letter.  Less frequently used settings are identified
+by one or more upper case letters, followed by a single lower case letter.
+
+For example, the setting @code{set print elements} is identified by
+the letter @code{e}.  The setting @code{set backtrace past-entry} is
+identified by the letters @code{Be}.
+
+@noindent
+Three types of settings can be temporarily changed by the @code{/} command:
+
+@table @code
+@item Boolean settings
+A boolean setting is temporarily activated (set to @code{on}) by
+giving its sequence of letters.  To temporarily deactivate (set to @code{off})
+a boolean setting, its sequence of letter must be prefixed by the
+exclamation mark character @code{!}.
+
+@item Unsigned integer settings
+An unsigned integer setting is temporarily changed by giving the desired
+numeric value followed by its sequence of letters.  If no numeric value
+preceedes the setting, the setting is temporarily changed to unlimited.
+The value 0 also indicates to change the setting to unlimited.
+
+@item Enumeration settings
+An enumeration setting is temporarily changed by giving its sequence
+of letters followed by a single character designating the chosen
+enumeration value.  For example, the letter @code{l} identifies
+the @code{set language} setting.  Using @code{/lA print somevar}
+will temporarily change the language to Ada (identified by the letter
+@code{A}) to execute the command @code{print somevar}, while
+@code{/lf print somevar} will rather switch to fortran.
+
+@end table
+
+To change several settings for the same command, just append each
+desired setting once after each other.  For example, @code{/lA10e}
+will temporarily change the language to Ada and set a limit of 10 elements
+to print for arrays and strings.
+
+The following table gives the list of settings that the @code{/} command
+can temporarily change.  The first column gives the letter sequence
+identifying the setting corresponding to the command in the second column.
+The third column gives the type of the setting, and list the different
+possible values for the enumeration settings.  Note that the below table
+is produced by the @code{help /} command.
+
+@smallexample
+@c In the 'doc' build directory, the following can be produced by:
+@c ../../gdb/gdb -q --nx  -ex 'set width 80' -ex 'set height 0' -ex 'help /' -ex quit |
+@c   sed -e '1,/The temporarily changeable settings are:/d' -e ':a;s/^\( *\) /@\1/;ta' -e 's/^/@exdent /'
+@c Maybe this could/should be automated by the doc Makefile ?
+@exdent /Be       set backtrace past-entry       Boolean on|off
+@exdent /Bl       set backtrace limit            Unsigned integer (0 means unlimited)
+@exdent /Bm       set backtrace past-main        Boolean on|off
+@exdent /Co       set print object               Boolean on|off
+@exdent /Cs       set print static-members       Boolean on|off
+@exdent /Cv       set print vtbl                 Boolean on|off
+@exdent /Pa       set print address              Boolean on|off
+@exdent /Ps       set print symbol               Boolean on|off
+@exdent /Rf       set print raw frame-arguments  Boolean on|off
+@exdent /a        set print array                Boolean on|off
+@exdent /e        set print elements             Unsigned integer (0 means unlimited)
+@exdent /f[asn]   set print frame-arguments      Enum, a = all, s = scalars, n = none
+@exdent /i        set print array-indexes        Boolean on|off
+@exdent /l[aluAscCdfgmMOo] set language          Enum, a = auto, l = local,
+@exdent @                               u = unknown, A = ada, s = asm, c = c, C = c++,
+@exdent @                               d = d, f = fortran, g = go, m = minimal,
+@exdent @                               M = modula-2, O = objective-c, o = opencl
+@exdent /n        set print null-stop            Boolean on|off
+@exdent /p        set print pretty               Boolean on|off
+@exdent /r        set print repeats              Unsigned integer (0 means unlimited)
+@exdent /u        set print union                Boolean on|off
+@exdent /v        set varsize-limit              Unsigned integer (0 means unlimited)
+@end smallexample
+
 @node Completion
 @section Command Completion