PR gdb/21122: Fix documentation mistakes for breakpoint commands

Currently, the breakpoint documentation refers to some commands taking breakpoint
"ranges" as arguments. We discussed this with Pedro and concluded that it would
be more accurate to speak in terms of breakpoint "lists", whose elements can optionally
be ranges. I also fixed a couple of minor mistakes in the docs.

gdb/ChangeLog:

	* breakpoint.c (_initialize_breakpoint): Update the help description
	of the 'commands' command to indicate that it takes a list argument.

gdb/doc/ChangeLog:

	* gdb.texinfo (Breakpoints): Reword documentation to speak in terms of
	space-separated breakpoint lists.  Also add a missing @table command
	and @cindex for breakpoint lists.

gdb/testsuite/ChangeLog:

	* gdb.base/help.exp: Update match pattern for testing 'help commands'.

diff --git a/gdb/ChangeLog b/gdb/ChangeLog
index 85bb98c..5902857 100644 (file)
--- a/gdb/ChangeLog
+++ b/gdb/ChangeLog
@@ -1,3 +1,9 @@
+2017-02-10  Martin Galvan  <martingalvan@sourceware.org>
+
+       PR gdb/21122
+       * breakpoint.c (_initialize_breakpoint): Update the help description
+       of the 'commands' command to indicate that it takes a list argument.
+
 2017-02-09  Simon Marchi  <simon.marchi@ericsson.com>
 
        * interps.c (current_interp_set_logging): Remove "return".

diff --git a/gdb/breakpoint.c b/gdb/breakpoint.c
index a76b3e4..ab6e9c8 100644 (file)
--- a/gdb/breakpoint.c
+++ b/gdb/breakpoint.c
@@ -16165,8 +16165,10 @@ Set ignore-count of breakpoint number N to COUNT.\n\
 Usage is `ignore N COUNT'."));
 
   add_com ("commands", class_breakpoint, commands_command, _("\
-Set commands to be executed when a breakpoint is hit.\n\
-Give breakpoint number as argument after \"commands\".\n\
+Set commands to be executed when the given breakpoints are hit.\n\
+Give a space-separated breakpoint list as argument after \"commands\".\n\
+A list element can be a breakpoint number (e.g. `5') or a range of numbers\n\
+(e.g. `5-7').\n\
 With no argument, the targeted breakpoint is the last one set.\n\
 The commands themselves follow starting on the next line.\n\
 Type a line containing \"end\" to indicate the end of them.\n\

diff --git a/gdb/doc/ChangeLog b/gdb/doc/ChangeLog
index 9b5e140..8acc482 100644 (file)
--- a/gdb/doc/ChangeLog
+++ b/gdb/doc/ChangeLog
@@ -1,3 +1,10 @@
+2017-02-10  Martin Galvan  <martingalvan@sourceware.org>
+
+       PR gdb/21122
+       * gdb.texinfo (Breakpoints): Reword documentation to speak in terms of
+       space-separated breakpoint lists.  Also add a missing @table command
+       and @cindex for breakpoint lists.
+
 2017-02-06  Ivo Raisr  <ivo.raisr@oracle.com>
 
        PR tdep/20936

diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index a969d1b..35804c1 100644 (file)
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -3588,12 +3588,14 @@ breakpoint you want to change.  Each breakpoint may be @dfn{enabled} or
 enable it again.
 
 @cindex breakpoint ranges
+@cindex breakpoint lists
 @cindex ranges of breakpoints
-Some @value{GDBN} commands accept a range of breakpoints on which to
-operate.  A breakpoint range is either a single breakpoint number, like
-@samp{5}, or two such numbers, in increasing order, separated by a
-hyphen, like @samp{5-7}.  When a breakpoint range is given to a command,
-all breakpoints in that range are operated on.
+@cindex lists of breakpoints
+Some @value{GDBN} commands accept a space-separated list of breakpoints
+on which to operate.  A list element can be either a single breakpoint number,
+like @samp{5}, or a range of such numbers, like @samp{5-7}.
+When a breakpoint list is given to a command, all breakpoints in that list
+are operated on.
 
 @menu
 * Set Breaks::                  Setting breakpoints
@@ -3758,8 +3760,8 @@ optionally be surrounded by spaces.
 
 @kindex info breakpoints
 @cindex @code{$_} and @code{info breakpoints}
-@item info breakpoints @r{[}@var{n}@dots{}@r{]}
-@itemx info break @r{[}@var{n}@dots{}@r{]}
+@item info breakpoints @r{[}@var{list}@dots{}@r{]}
+@itemx info break @r{[}@var{list}@dots{}@r{]}
 Print a table of all breakpoints, watchpoints, and catchpoints set and
 not deleted.  Optional argument @var{n} means print information only
 about the specified breakpoint(s) (or watchpoint(s) or catchpoint(s)).
@@ -3947,7 +3949,7 @@ breakpoints set by commands like @code{next} and @code{finish}.  For
 breakpoints set with @code{hbreak}, @value{GDBN} will always use hardware
 breakpoints.
 
-You can control this automatic behaviour with the following commands::
+You can control this automatic behaviour with the following commands:
 
 @kindex set breakpoint auto-hw
 @kindex show breakpoint auto-hw
@@ -4142,8 +4144,8 @@ by the program.
 Set a watchpoint that will break when @var{expr} is either read from
 or written into by the program.
 
-@kindex info watchpoints @r{[}@var{n}@dots{}@r{]}
-@item info watchpoints @r{[}@var{n}@dots{}@r{]}
+@kindex info watchpoints @r{[}@var{list}@dots{}@r{]}
+@item info watchpoints @r{[}@var{list}@dots{}@r{]}
 This command prints a list of watchpoints, using the same format as
 @code{info break} (@pxref{Set Breaks}).
 @end table
@@ -4639,9 +4641,9 @@ Delete any breakpoints set at or within the code of the specified
 @cindex delete breakpoints
 @kindex delete
 @kindex d @r{(@code{delete})}
-@item delete @r{[}breakpoints@r{]} @r{[}@var{range}@dots{}@r{]}
+@item delete @r{[}breakpoints@r{]} @r{[}@var{list}@dots{}@r{]}
 Delete the breakpoints, watchpoints, or catchpoints of the breakpoint
-ranges specified as arguments.  If no argument is specified, delete all
+list specified as argument.  If no argument is specified, delete all
 breakpoints (@value{GDBN} asks confirmation, unless you have @code{set
 confirm off}).  You can abbreviate this command as @code{d}.
 @end table
@@ -4691,7 +4693,7 @@ watchpoints, and catchpoints:
 @table @code
 @kindex disable
 @kindex dis @r{(@code{disable})}
-@item disable @r{[}breakpoints@r{]} @r{[}@var{range}@dots{}@r{]}
+@item disable @r{[}breakpoints@r{]} @r{[}@var{list}@dots{}@r{]}
 Disable the specified breakpoints---or all breakpoints, if none are
 listed.  A disabled breakpoint has no effect but is not forgotten.  All
 options such as ignore-counts, conditions and commands are remembered in
@@ -4699,15 +4701,15 @@ case the breakpoint is enabled again later.  You may abbreviate
 @code{disable} as @code{dis}.
 
 @kindex enable
-@item enable @r{[}breakpoints@r{]} @r{[}@var{range}@dots{}@r{]}
+@item enable @r{[}breakpoints@r{]} @r{[}@var{list}@dots{}@r{]}
 Enable the specified breakpoints (or all defined breakpoints).  They
 become effective once again in stopping your program.
 
-@item enable @r{[}breakpoints@r{]} once @var{range}@dots{}
+@item enable @r{[}breakpoints@r{]} once @var{list}@dots{}
 Enable the specified breakpoints temporarily.  @value{GDBN} disables any
 of these breakpoints immediately after stopping your program.
 
-@item enable @r{[}breakpoints@r{]} count @var{count} @var{range}@dots{}
+@item enable @r{[}breakpoints@r{]} count @var{count} @var{list}@dots{}
 Enable the specified breakpoints temporarily.  @value{GDBN} records
 @var{count} with each of the specified breakpoints, and decrements a
 breakpoint's count when it is hit.  When any count reaches 0,
@@ -4715,7 +4717,7 @@ breakpoint's count when it is hit.  When any count reaches 0,
 count (@pxref{Conditions, ,Break Conditions}), that will be
 decremented to 0 before @var{count} is affected.
 
-@item enable @r{[}breakpoints@r{]} delete @var{range}@dots{}
+@item enable @r{[}breakpoints@r{]} delete @var{list}@dots{}
 Enable the specified breakpoints to work once, then die.  @value{GDBN}
 deletes any of these breakpoints as soon as your program stops there.
 Breakpoints set by the @code{tbreak} command start out in this state.
@@ -4873,7 +4875,7 @@ enable other breakpoints.
 @table @code
 @kindex commands
 @kindex end@r{ (breakpoint commands)}
-@item commands @r{[}@var{range}@dots{}@r{]}
+@item commands @r{[}@var{list}@dots{}@r{]}
 @itemx @dots{} @var{command-list} @dots{}
 @itemx end
 Specify a list of commands for the given breakpoints.  The commands
@@ -4986,6 +4988,7 @@ dynamic printfs immediately.  (If you need individual control over the
 print commands, simply define normal breakpoints with
 explicitly-supplied command lists.)
 
+@table @code
 @item gdb
 @kindex dprintf-style gdb
 Handle the output using the @value{GDBN} @code{printf} command.
@@ -5000,6 +5003,7 @@ Handle the output by calling a function in your program (normally
 Have the remote debugging agent (such as @code{gdbserver}) handle
 the output itself.  This style is only available for agents that
 support running commands on the target.
+@end table
 
 @item set dprintf-function @var{function}
 Set the function to call if the dprintf style is @code{call}.  By

diff --git a/gdb/testsuite/ChangeLog b/gdb/testsuite/ChangeLog
index 39f6776..ed0d374 100644 (file)
--- a/gdb/testsuite/ChangeLog
+++ b/gdb/testsuite/ChangeLog
@@ -1,3 +1,8 @@
+2017-02-10  Martin Galvan  <martingalvan@sourceware.org>
+
+       PR gdb/21122
+       * gdb.base/help.exp: Update match pattern for testing 'help commands'.
+
 2017-02-08  Jerome Guitton  <guitton@adacore.com>
 
        * gdb.base/define.exp: Add test for command abbreviations

diff --git a/gdb/testsuite/gdb.base/help.exp b/gdb/testsuite/gdb.base/help.exp
index 0043642..58f4b5d 100644 (file)
--- a/gdb/testsuite/gdb.base/help.exp
+++ b/gdb/testsuite/gdb.base/help.exp
@@ -78,7 +78,7 @@ gdb_test "help bt" $help_backtrace_text "help backtrace \"bt\" abbreviation"
 gdb_test "help backtrace" $help_backtrace_text "help backtrace"
 
 # test help commands
-gdb_test "help commands" "Set commands to be executed when a breakpoint is hit\.\[\r\n\]+Give breakpoint number as argument after \"commands\"\.\[\r\n\]+With no argument, the targeted breakpoint is the last one set\.\[\r\n\]+The commands themselves follow starting on the next line\.\[\r\n\]+Type a line containing \"end\" to indicate the end of them\.\[\r\n\]+Give \"silent\" as the first line to make the breakpoint silent;\[\r\n\]+then no output is printed when it is hit, except what the commands print\." "help commands"
+gdb_test "help commands" "Set commands to be executed when the given breakpoints are hit\.\[\r\n\]+Give a space-separated breakpoint list as argument after \"commands\"\.\[\r\n\]+A list element can be a breakpoint number \\(e.g. `5'\\) or a range of numbers\[\r\n\]+\\(e.g. `5-7'\\)\.\[\r\n\]+With no argument, the targeted breakpoint is the last one set\.\[\r\n\]+The commands themselves follow starting on the next line\.\[\r\n\]+Type a line containing \"end\" to indicate the end of them\.\[\r\n\]+Give \"silent\" as the first line to make the breakpoint silent;\[\r\n\]+then no output is printed when it is hit, except what the commands print\." "help commands"
 
 # Test a prefix command.  "delete" is picked at random.
 # test help delete "d" abbreviation