[PATCH] Improve built-in documentation for pagination commands

[PATCH] Improve built-in documentation for pagination commands

[Eli Zaretskii]

I frequently waste too much time looking up these commands, because I
constantly forget their names.  So I decided to improve their doc
strings so that 'apropos' will find them easier, and also to mention
the special value of zero explicitly.

Any objections to the changeset below?

gdb/ChangeLog:

2013-03-07  Eli Zaretskii  <eliz@gnu.org>

	* utils.c (initialize_utils): Improve doc strings of "set/show
	width", "set/show height", and "set/show pagination".


--- gdb/utils.c~0	2012-07-02 13:57:33.000000000 +0300
+++ gdb/utils.c	2013-03-07 12:01:41.951125000 +0200
@@ -2654,15 +2654,20 @@
 initialize_utils (void)
 {
   add_setshow_uinteger_cmd ("width", class_support, &chars_per_line, _("\
-Set number of characters gdb thinks are in a line."), _("\
-Show number of characters gdb thinks are in a line."), NULL,
+Set number of characters where GDB should wrap lines of its output."), _("\
+Show number of characters where GDB should wrap lines of its output."), _("\
+This affects where GDB wraps its output to fit the screen width.\n\
+Setting this to zero prevents GDB from wrapping its output."),
 			    set_width_command,
 			    show_chars_per_line,
 			    &setlist, &showlist);
 
   add_setshow_uinteger_cmd ("height", class_support, &lines_per_page, _("\
-Set number of lines gdb thinks are in a page."), _("\
-Show number of lines gdb thinks are in a page."), NULL,
+Set number of lines in a page for GDB output pagination."), _("\
+Show number of lines in a page for GDB output pagination."), _("\
+This affects the number of lines after which GDB will pause\n\
+its output and ask you whether to continue.\n\
+Setting this to zero causes GDB never pause during output."),
 			    set_height_command,
 			    show_lines_per_page,
 			    &setlist, &showlist);
@@ -2671,8 +2676,11 @@
 
   add_setshow_boolean_cmd ("pagination", class_support,
 			   &pagination_enabled, _("\
-Set state of pagination."), _("\
-Show state of pagination."), NULL,
+Set state of GDB output pagination."), _("\
+Show state of GDB output pagination."), _("\
+When pagination is ON, GDB pauses at end of each screenful of\n\
+its output and asks you whether to continue.\n\
+Turning pagination off is an alternative to \"set height 0\"."),
 			   NULL,
 			   show_pagination_enabled,
 			   &setlist, &showlist);


gdb/testsuite/ChangeLog:

2013-03-07  Eli Zaretskii  <eliz@gnu.org>

	* gdb.base/help.exp: Adjust test case to match changes in GDB
	output of "set/show height", "set/show width", and "set/show
	pagination" commands.


--- gdb/testsuite/gdb.base/help.exp~0	2012-07-02 20:53:19.000000000 +0300
+++ gdb/testsuite/gdb.base/help.exp	2013-03-07 12:03:02.607375000 +0200
@@ -401,7 +401,7 @@
 # test help set environment
 gdb_test "help set environment" "Set environment variable value to give the program\.\[\r\n\]+Arguments are VAR VALUE where VAR is variable name and VALUE is value\.\[\r\n\]+VALUES of environment variables are uninterpreted strings\.\[\r\n\]+This does not affect the program until the next \"run\" command\." "help set environment"
 # test help set height
-gdb_test "help set height" "Set number of lines gdb thinks are in a page\." "help set height"
+gdb_test "help set height" "Set number of lines in a page for GDB output pagination\.\[\r\n\]+This affects the number of lines after which GDB will pause\[\r\n\]+its output and ask you whether to continue\.\[\r\n\]+Setting this to zero GDB never pauses during output\." "help set height"
 # test help set history expansion
 gdb_test "help set history expansion" "Set history expansion on command input\.\[\r\n\]+Without an argument, history expansion is enabled\." "help set history expansion"
 # test help set history filename
@@ -463,7 +463,7 @@
 # test help set verbose
 gdb_test "help set verbose" "Set verbosity\." "help set verbose"
 #test help set width
-gdb_test "help set width" "Set number of characters gdb thinks are in a line\." "help set width"
+gdb_test "help set width" "Set number of characters where GDB should wrap lines of its output.\.\[\r\n\]+This affects where GDB wraps its output to fit the screen width\.\[\r\n\]+Setting this to zero prevents GDB from wrapping its output\." "help set width"
 # test help set write
 # This is only supported on targets which use exec.o.
 gdb_test "help set write" "Set writing into executable and core files\." "help set write"
@@ -514,7 +514,7 @@
 # test help show environment
 gdb_test "help show environment" "The environment to give the program, or one variable's value\.\[\r\n\]+With an argument VAR, prints the value of environment variable VAR to\[\r\n\]+give the program being debugged\.  With no arguments, prints the entire\[\r\n\]+environment to be given to the program\." "help show environment"
 # test help show height
-gdb_test "help show height" "Show number of lines gdb thinks are in a page\." "help show height"
+gdb_test "help show height" "Show number of lines in a page for GDB output pagination\.\[\r\n\]+This affects the number of lines after which GDB will pause\[\r\n\]+its output and ask you whether to continue\.\[\r\n\]+Setting this to zero GDB never pause during output\." "help show height"
 # test help show history expansion
 gdb_test "help show history expansion" "Show history expansion on command input\.\[\r\n\]+Without an argument, history expansion is enabled\." "help show history expansion"
 # test help show history filename
@@ -578,7 +578,7 @@
 # test help show version
 gdb_test "help show version" "Show what version of GDB this is\." "help show version"
 # test help show width
-gdb_test "help show width" "Show number of characters gdb thinks are in a line\." "help show width"
+gdb_test "help show width" "Show number of characters where GDB should wrap lines of its output\.\[\r\n\]+This affects where GDB wraps its output to fit the screen width\.\[\r\n\]+Setting this to zero prevents GDB from wrapping its output\." "help show width"
 # test help show write
 # This is only supported on targets which use exec.o.
 gdb_test "help show write" "Show writing into executable and core files\." "help show write"

Re: [PATCH] Improve built-in documentation for pagination commands

[Pedro Alves]

On 03/07/2013 10:08 AM, Eli Zaretskii wrote:
> I frequently waste too much time looking up these commands, because I
> constantly forget their names.  So I decided to improve their doc
> strings so that 'apropos' will find them easier, and also to mention
> the special value of zero explicitly.
> 
> Any objections to the changeset below?

I think this looks great.

-- 
Pedro Alves

Re: [PATCH] Improve built-in documentation for pagination commands

[Eli Zaretskii]

> Date: Thu, 07 Mar 2013 10:36:39 +0000
> From: Pedro Alves <palves@redhat.com>
> CC: gdb-patches@sourceware.org
> 
> On 03/07/2013 10:08 AM, Eli Zaretskii wrote:
> > I frequently waste too much time looking up these commands, because I
> > constantly forget their names.  So I decided to improve their doc
> > strings so that 'apropos' will find them easier, and also to mention
> > the special value of zero explicitly.
> > 
> > Any objections to the changeset below?
> 
> I think this looks great.

Thanks, I committed that (sans the testsuite part, which is no longer
necessary, since help.exp had the command-specific help text removed).