[RFA 00/12] Small help text tweaks

[RFA 00/12] Small help text tweaks

[Tom Tromey]

I've long understood the GNU style for "metasyntactic variables" --
text that is a placeholder for some value -- to be to write them in
all caps.  For example, from "gdb --help":

  --core=COREFILE    Analyze the core dump COREFILE.

However, while researching for this post, I couldn't actually find
this in the GNU coding standards -- I thought it was there, but the
closest I could find was in the Emacs Lisp manual.

Nevertheless, I'm pressing forward with this series, which fixes a
number of spots in gdb to use this style in the help text for
commands.

I found the commands to change using "apropos <" -- since the most
common alternate style is to wrap a metasyntactic with <>.

Regression tested by the buildbot.

Tom

[RFA 08/12] Update help text in disasm.c

[Tom Tromey]

This changes some help text in disasm.c to follow the GNU style.

2018-04-29  Tom Tromey  <tom@tromey.com>

	* disasm.c (_initialize_disasm): Update help text.
---
 gdb/ChangeLog | 4 ++++
 gdb/disasm.c  | 2 +-
 2 files changed, 5 insertions(+), 1 deletion(-)

diff --git a/gdb/disasm.c b/gdb/disasm.c
index 833341a169..e465388204 100644
--- a/gdb/disasm.c
+++ b/gdb/disasm.c
@@ -1036,7 +1036,7 @@ _initialize_disasm (void)
   cmd = add_setshow_string_noescape_cmd ("disassembler-options", no_class,
 					 &prospective_options, _("\
 Set the disassembler options.\n\
-Usage: set disassembler-options <option>[,<option>...]\n\n\
+Usage: set disassembler-options OPTION [,OPTION]...\n\n\
 See: 'show disassembler-options' for valid option values.\n"), _("\
 Show the disassembler options."), NULL,
 					 set_disassembler_options_sfunc,
-- 
2.13.6

Re: [RFA 08/12] Update help text in disasm.c

[Pedro Alves]

On 04/30/2018 03:37 PM, Tom Tromey wrote:
> This changes some help text in disasm.c to follow the GNU style.
> 
> 2018-04-29  Tom Tromey  <tom@tromey.com>
> 
> 	* disasm.c (_initialize_disasm): Update help text.

OK.

Thanks,
Pedro Alves

[RFA 12/12] Update help text in record.c

[Tom Tromey]

This updates some help text in record.c to conform to GNU standards.
I also added a "Usage" line to "record save".

2018-04-29  Tom Tromey  <tom@tromey.com>

	* record.c (_initialize_record): Update help text.
---
 gdb/ChangeLog | 4 ++++
 gdb/record.c  | 4 ++--
 2 files changed, 6 insertions(+), 2 deletions(-)

diff --git a/gdb/record.c b/gdb/record.c
index d7befb2a74..4ecfc8f418 100644
--- a/gdb/record.c
+++ b/gdb/record.c
@@ -822,8 +822,8 @@ A size of \"unlimited\" means unlimited lines.  The default is 10."),
 
   c = add_cmd ("save", class_obscure, cmd_record_save,
 	       _("Save the execution log to a file.\n\
-Argument is optional filename.\n\
-Default filename is 'gdb_record.<process_id>'."),
+Usage: record save [FILENAME]\n\
+Default filename is 'gdb_record.PROCESS_ID'."),
 	       &record_cmdlist);
   set_cmd_completer (c, filename_completer);
 
-- 
2.13.6

Re: [RFA 12/12] Update help text in record.c

[Pedro Alves]

On 04/30/2018 03:37 PM, Tom Tromey wrote:

> diff --git a/gdb/record.c b/gdb/record.c
> index d7befb2a74..4ecfc8f418 100644
> --- a/gdb/record.c
> +++ b/gdb/record.c
> @@ -822,8 +822,8 @@ A size of \"unlimited\" means unlimited lines.  The default is 10."),
>  
>    c = add_cmd ("save", class_obscure, cmd_record_save,
>  	       _("Save the execution log to a file.\n\
> -Argument is optional filename.\n\
> -Default filename is 'gdb_record.<process_id>'."),
> +Usage: record save [FILENAME]\n\
> +Default filename is 'gdb_record.PROCESS_ID'."),

Same as in the other patch, about PROCESS_ID not being user
input here.

Otherwise OK.

Thanks,
Pedro Alves

[RFA 02/12] Update help strings in skip.c

[Tom Tromey]

This changes help strings in skip.c to follow the GNU style.

2018-04-27  Tom Tromey  <tom@tromey.com>

	* skip.c (_initialize_step_skip): Update help strings.
---
 gdb/ChangeLog |  4 ++++
 gdb/skip.c    | 14 +++++++-------
 2 files changed, 11 insertions(+), 7 deletions(-)

diff --git a/gdb/skip.c b/gdb/skip.c
index ad80fa3826..7a6f2e712b 100644
--- a/gdb/skip.c
+++ b/gdb/skip.c
@@ -610,13 +610,13 @@ _initialize_step_skip (void)
 Ignore a function while stepping.\n\
 \n\
 Usage: skip [FUNCTION-NAME]\n\
-       skip [<file-spec>] [<function-spec>]\n\
+       skip [FILE-SPEC] [FUNCTION-SPEC]\n\
 If no arguments are given, ignore the current function.\n\
 \n\
-<file-spec> is one of:\n\
+FILE-SPEC is one of:\n\
        -fi|-file FILE-NAME\n\
        -gfi|-gfile GLOB-FILE-PATTERN\n\
-<function-spec> is one of:\n\
+FUNCTION-SPEC is one of:\n\
        -fu|-function FUNCTION-NAME\n\
        -rfu|-rfunction FUNCTION-NAME-REGULAR-EXPRESSION"),
                   &skiplist, "skip ", 1, &cmdlist);
@@ -639,28 +639,28 @@ If no function name is given, skip the current function."),
 Enable skip entries.  You can specify numbers (e.g. \"skip enable 1 3\"), \
 ranges (e.g. \"skip enable 4-8\"), or both (e.g. \"skip enable 1 3 4-8\").\n\n\
 If you don't specify any numbers or ranges, we'll enable all skip entries.\n\n\
-Usage: skip enable [NUMBERS AND/OR RANGES]"),
+Usage: skip enable [NUMBER | RANGE]..."),
 	   &skiplist);
 
   add_cmd ("disable", class_breakpoint, skip_disable_command, _("\
 Disable skip entries.  You can specify numbers (e.g. \"skip disable 1 3\"), \
 ranges (e.g. \"skip disable 4-8\"), or both (e.g. \"skip disable 1 3 4-8\").\n\n\
 If you don't specify any numbers or ranges, we'll disable all skip entries.\n\n\
-Usage: skip disable [NUMBERS AND/OR RANGES]"),
+Usage: skip disable [NUMBER | RANGE]..."),
 	   &skiplist);
 
   add_cmd ("delete", class_breakpoint, skip_delete_command, _("\
 Delete skip entries.  You can specify numbers (e.g. \"skip delete 1 3\"), \
 ranges (e.g. \"skip delete 4-8\"), or both (e.g. \"skip delete 1 3 4-8\").\n\n\
 If you don't specify any numbers or ranges, we'll delete all skip entries.\n\n\
-Usage: skip delete [NUMBERS AND/OR RANGES]"),
+Usage: skip delete [NUMBER | RANGES]..."),
            &skiplist);
 
   add_info ("skip", info_skip_command, _("\
 Display the status of skips.  You can specify numbers (e.g. \"skip info 1 3\"), \
 ranges (e.g. \"skip info 4-8\"), or both (e.g. \"skip info 1 3 4-8\").\n\n\
 If you don't specify any numbers or ranges, we'll show all skips.\n\n\
-Usage: skip info [NUMBERS AND/OR RANGES]\n\
+Usage: skip info [NUMBER | RANGES]...\n\
 The \"Type\" column indicates one of:\n\
 \tfile        - ignored file\n\
 \tfunction    - ignored function"));
-- 
2.13.6

Re: [RFA 02/12] Update help strings in skip.c

[Pedro Alves]

On 04/30/2018 03:37 PM, Tom Tromey wrote:
> This changes help strings in skip.c to follow the GNU style.
> 
> 2018-04-27  Tom Tromey  <tom@tromey.com>
> 
> 	* skip.c (_initialize_step_skip): Update help strings.

OK.

Thanks,
Pedro Alves

[RFA 06/12] Update help text in dcache.c

[Tom Tromey]

This updates some text in dcache.c to follow GNU standards.
Here, I found a couple of spots needing an update.

2018-04-29  Tom Tromey  <tom@tromey.com>

	* dcache.c (dcache_info_1): Update usage text.
	(_initialize_dcache): Update help text.
---
 gdb/ChangeLog | 5 +++++
 gdb/dcache.c  | 7 ++++---
 2 files changed, 9 insertions(+), 3 deletions(-)

diff --git a/gdb/dcache.c b/gdb/dcache.c
index 805f492bd7..20b781fa01 100644
--- a/gdb/dcache.c
+++ b/gdb/dcache.c
@@ -595,7 +595,7 @@ dcache_info_1 (DCACHE *dcache, const char *exp)
       i = strtol (exp, &linestart, 10);
       if (linestart == exp || i < 0)
 	{
-	  printf_filtered (_("Usage: info dcache [linenumber]\n"));
+	  printf_filtered (_("Usage: info dcache [LINENUMBER]\n"));
           return;
 	}
 
@@ -701,9 +701,10 @@ exists only for compatibility reasons."),
   add_info ("dcache", info_dcache_command,
 	    _("\
 Print information on the dcache performance.\n\
+Usage: info dcache [LINENUMBER]\n\
 With no arguments, this command prints the cache configuration and a\n\
-summary of each line in the cache.  Use \"info dcache <lineno> to dump\"\n\
-the contents of a given line."));
+summary of each line in the cache.  With an argument, dump\"\n\
+the contents of the given line."));
 
   add_prefix_cmd ("dcache", class_obscure, set_dcache_command, _("\
 Use this command to set number of lines in dcache and line-size."),
-- 
2.13.6

Re: [RFA 06/12] Update help text in dcache.c

[Pedro Alves]

On 04/30/2018 03:37 PM, Tom Tromey wrote:
> This updates some text in dcache.c to follow GNU standards.
> Here, I found a couple of spots needing an update.

OK.

Thanks,
Pedro Alves

[RFA 09/12] Update help text in tracepoint.c

[Tom Tromey]

This changes the help text of a couple of commands in tracepoint.c to
follow the GNU style.

ChangeLog
2018-04-29  Tom Tromey  <tom@tromey.com>

	* tracepoint.c (_initialize_tracepoint): Update help text.

testsuite/ChangeLog
2018-04-30  Tom Tromey  <tom@tromey.com>

	* gdb.trace/tfind.exp: Update help tests.
---
 gdb/ChangeLog                     | 4 ++++
 gdb/testsuite/ChangeLog           | 4 ++++
 gdb/testsuite/gdb.trace/tfind.exp | 4 ++--
 gdb/tracepoint.c                  | 4 ++--
 4 files changed, 12 insertions(+), 4 deletions(-)

diff --git a/gdb/testsuite/gdb.trace/tfind.exp b/gdb/testsuite/gdb.trace/tfind.exp
index c466862333..bbb7ec829d 100644
--- a/gdb/testsuite/gdb.trace/tfind.exp
+++ b/gdb/testsuite/gdb.trace/tfind.exp
@@ -34,11 +34,11 @@ gdb_test "tfind none"  ".*" ""
 
 # 6.2 test help tstart
 gdb_test "help tstart" \
-    "Start trace data collection\.\[\r\n\]+Usage: tstart \\\[ <notes> \.\.\. \\\]\[\r\n\]+Any arguments supplied are recorded with the trace as a note and\[\r\n\]+reported by tstatus \\(if the target supports trace notes\\)\." \
+    "Start trace data collection\.\[\r\n\]+Usage: tstart \\\[NOTES\\\]\.\.\.\[\r\n\]+Any arguments supplied are recorded with the trace as a note and\[\r\n\]+reported by tstatus \\(if the target supports trace notes\\)\." \
     "6.2: help tstart"
 # 7.2 test help tstop
 gdb_test "help tstop" \
-    "Stop trace data collection\.\[\r\n\]+Usage: tstop \\\[ <notes> \.\.\. \\\]\[\r\n\]+Any arguments supplied are recorded with the trace as a stop reason and\[\r\n\]+reported by tstatus \\(if the target supports trace notes\\)\." \
+    "Stop trace data collection\.\[\r\n\]+Usage: tstop \\\[NOTES\\\]\.\.\.\[\r\n\]+Any arguments supplied are recorded with the trace as a stop reason and\[\r\n\]+reported by tstatus \\(if the target supports trace notes\\)\." \
     "7.2: help tstop"
 
 # 8.38 test help tfind
diff --git a/gdb/tracepoint.c b/gdb/tracepoint.c
index 7e173ce75d..eff86756c6 100644
--- a/gdb/tracepoint.c
+++ b/gdb/tracepoint.c
@@ -4086,13 +4086,13 @@ De-select any trace frame and resume 'live' debugging."),
 
   add_com ("tstop", class_trace, tstop_command, _("\
 Stop trace data collection.\n\
-Usage: tstop [ <notes> ... ]\n\
+Usage: tstop [NOTES]...\n\
 Any arguments supplied are recorded with the trace as a stop reason and\n\
 reported by tstatus (if the target supports trace notes)."));
 
   add_com ("tstart", class_trace, tstart_command, _("\
 Start trace data collection.\n\
-Usage: tstart [ <notes> ... ]\n\
+Usage: tstart [NOTES]...\n\
 Any arguments supplied are recorded with the trace as a note and\n\
 reported by tstatus (if the target supports trace notes)."));
 
-- 
2.13.6

Re: [RFA 09/12] Update help text in tracepoint.c

[Pedro Alves]

On 04/30/2018 03:37 PM, Tom Tromey wrote:
> This changes the help text of a couple of commands in tracepoint.c to
> follow the GNU style.
> 
> ChangeLog
> 2018-04-29  Tom Tromey  <tom@tromey.com>
> 
> 	* tracepoint.c (_initialize_tracepoint): Update help text.
> 
> testsuite/ChangeLog
> 2018-04-30  Tom Tromey  <tom@tromey.com>
> 
> 	* gdb.trace/tfind.exp: Update help tests.

OK.

Thanks,
Pedro Alves

[RFA 05/12] Update help strings in TUI

[Tom Tromey]

This updates some help strings in the TUI to more closely follow GNU
standards.  In this case I chose to reuse some existing "usage" macros
in the help text.  Also, I found that XDBWIN_HEIGHT_USAGE is unused,
so I removed it.

ChangeLog
2018-04-29  Tom Tromey  <tom@tromey.com>

	* tui/tui-layout.c (_initialize_tui_layout): Update help text.
	* tui/tui-win.c (WIN_HEIGHT_USAGE, FOCUS_USAGE): Update
	(XDBWIN_HEIGHT_USAGE): Remove.
	(_initialize_tui_win): Use macros.  Update help text.
---
 gdb/ChangeLog        |  7 +++++++
 gdb/tui/tui-layout.c |  2 +-
 gdb/tui/tui-win.c    | 27 +++++++++++++--------------
 3 files changed, 21 insertions(+), 15 deletions(-)

diff --git a/gdb/tui/tui-layout.c b/gdb/tui/tui-layout.c
index 8e15f4e705..66e8e45f37 100644
--- a/gdb/tui/tui-layout.c
+++ b/gdb/tui/tui-layout.c
@@ -374,7 +374,7 @@ _initialize_tui_layout (void)
 
   cmd = add_com ("layout", class_tui, tui_layout_command, _("\
 Change the layout of windows.\n\
-Usage: layout prev | next | <layout_name> \n\
+Usage: layout prev | next | LAYOUT-NAME\n\
 Layout names are:\n\
    src   : Displays source and command windows.\n\
    asm   : Displays disassembly and command windows.\n\
diff --git a/gdb/tui/tui-win.c b/gdb/tui/tui-win.c
index f3b7873d53..c42d7f036c 100644
--- a/gdb/tui/tui-win.c
+++ b/gdb/tui/tui-win.c
@@ -78,9 +78,8 @@ static void parse_scrolling_args (const char *,
 /***************************************
 ** DEFINITIONS
 ***************************************/
-#define WIN_HEIGHT_USAGE    "Usage: winheight <win_name> [+ | -] <#lines>\n"
-#define XDBWIN_HEIGHT_USAGE "Usage: w <#lines>\n"
-#define FOCUS_USAGE         "Usage: focus {<win> | next | prev}\n"
+#define WIN_HEIGHT_USAGE    "Usage: winheight WINDOW-NAME> [+ | -] NUM-LINES>\n"
+#define FOCUS_USAGE         "Usage: focus [WINDOW-NAME | next | prev]\n"
 
 /***************************************
 ** PUBLIC FUNCTIONS
@@ -456,11 +455,11 @@ _initialize_tui_win (void)
            _("Refresh the terminal display.\n"));
   add_com ("tabset", class_tui, tui_set_tab_width_command, _("\
 Set the width (in characters) of tab stops.\n\
-Usage: tabset <n>\n"));
+Usage: tabset N\n"));
   cmd = add_com ("winheight", class_tui, tui_set_win_height_command, _("\
-Set or modify the height of a specified window.\n\
-Usage: winheight <win_name> [+ | -] <#lines>\n\
-Window names are:\n\
+Set or modify the height of a specified window.\n"
+WIN_HEIGHT_USAGE
+"Window names are:\n\
 src  : the source window\n\
 cmd  : the command window\n\
 asm  : the disassembly window\n\
@@ -470,9 +469,9 @@ regs : the register display\n"));
   add_info ("win", tui_all_windows_info,
 	    _("List of all displayed windows.\n"));
   cmd = add_com ("focus", class_tui, tui_set_focus_command, _("\
-Set focus to named window or next/prev window.\n\
-Usage: focus {<win> | next | prev}\n\
-Valid Window names are:\n\
+Set focus to named window or next/prev window.\n"
+FOCUS_USAGE
+"Valid Window names are:\n\
 src  : the source window\n\
 asm  : the disassembly window\n\
 regs : the register display\n\
@@ -481,16 +480,16 @@ cmd  : the command window\n"));
   set_cmd_completer (cmd, focus_completer);
   add_com ("+", class_tui, tui_scroll_forward_command, _("\
 Scroll window forward.\n\
-Usage: + [win] [n]\n"));
+Usage: + [WIN] [N]\n"));
   add_com ("-", class_tui, tui_scroll_backward_command, _("\
 Scroll window backward.\n\
-Usage: - [win] [n]\n"));
+Usage: - [WIN] [N]\n"));
   add_com ("<", class_tui, tui_scroll_left_command, _("\
 Scroll window text to the left.\n\
-Usage: < [win] [n]\n"));
+Usage: < [WIN] [N]\n"));
   add_com (">", class_tui, tui_scroll_right_command, _("\
 Scroll window text to the right.\n\
-Usage: > [win] [n]\n"));
+Usage: > [WIN] [N]\n"));
 
   /* Define the tui control variables.  */
   add_setshow_enum_cmd ("border-kind", no_class, tui_border_kind_enums,
-- 
2.13.6

Re: [RFA 05/12] Update help strings in TUI

[Pedro Alves]

On 04/30/2018 03:37 PM, Tom Tromey wrote:
> This updates some help strings in the TUI to more closely follow GNU
> standards.  In this case I chose to reuse some existing "usage" macros
> in the help text.  Also, I found that XDBWIN_HEIGHT_USAGE is unused,
> so I removed it.

OK.

Thanks,
Pedro Alves

[RFA 03/12] Update core-related help strings

[Tom Tromey]

This updates some help strings in corefile.c and gcore.c.

2018-04-27  Tom Tromey  <tom@tromey.com>

	* corefile.c (_initialize_core): Update help string.
	* gcore.c (_initialize_gcore): Update help string.
---
 gdb/ChangeLog  | 5 +++++
 gdb/corefile.c | 1 +
 gdb/gcore.c    | 3 ++-
 3 files changed, 8 insertions(+), 1 deletion(-)

diff --git a/gdb/corefile.c b/gdb/corefile.c
index 5a735264ef..d8f30cf804 100644
--- a/gdb/corefile.c
+++ b/gdb/corefile.c
@@ -509,6 +509,7 @@ _initialize_core (void)
 
   c = add_cmd ("core-file", class_files, core_file_command, _("\
 Use FILE as core dump for examining memory and registers.\n\
+Usage: core-file FILE\n\
 No arg means have no core file.  This command has been superseded by the\n\
 `target core' and `detach' commands."), &cmdlist);
   set_cmd_completer (c, filename_completer);
diff --git a/gdb/gcore.c b/gdb/gcore.c
index 5ff4e6dc77..c53810049c 100644
--- a/gdb/gcore.c
+++ b/gdb/gcore.c
@@ -611,7 +611,8 @@ _initialize_gcore (void)
 {
   add_com ("generate-core-file", class_files, gcore_command, _("\
 Save a core file with the current state of the debugged process.\n\
-Argument is optional filename.  Default filename is 'core.<process_id>'."));
+Usage: generate-core-file [FILENAME]\n\
+Argument is optional filename.  Default filename is 'core.PROCESS_ID'."));
 
   add_com_alias ("gcore", "generate-core-file", class_files, 1);
 }
-- 
2.13.6

Re: [RFA 03/12] Update core-related help strings

[Pedro Alves]

On 04/30/2018 03:37 PM, Tom Tromey wrote:

> diff --git a/gdb/gcore.c b/gdb/gcore.c
> index 5ff4e6dc77..c53810049c 100644
> --- a/gdb/gcore.c
> +++ b/gdb/gcore.c
> @@ -611,7 +611,8 @@ _initialize_gcore (void)
>  {
>    add_com ("generate-core-file", class_files, gcore_command, _("\
>  Save a core file with the current state of the debugged process.\n\
> -Argument is optional filename.  Default filename is 'core.<process_id>'."));
> +Usage: generate-core-file [FILENAME]\n\
> +Argument is optional filename.  Default filename is 'core.PROCESS_ID'."));

Do the guidelines say anything about this?  I mean, PROCESS_ID is not
user input, so I'm wondering whether it should be all caps, or whether
it was better as it was.

Otherwise looks fine.

Thanks,
Pedro Alves

Re: [RFA 03/12] Update core-related help strings

[Tom Tromey]

>>>>> "Pedro" == Pedro Alves <palves@redhat.com> writes:

Pedro> On 04/30/2018 03:37 PM, Tom Tromey wrote:
>> diff --git a/gdb/gcore.c b/gdb/gcore.c
>> index 5ff4e6dc77..c53810049c 100644
>> --- a/gdb/gcore.c
>> +++ b/gdb/gcore.c
>> @@ -611,7 +611,8 @@ _initialize_gcore (void)
>> {
>> add_com ("generate-core-file", class_files, gcore_command, _("\
>> Save a core file with the current state of the debugged process.\n\
>> -Argument is optional filename.  Default filename is 'core.<process_id>'."));
>> +Usage: generate-core-file [FILENAME]\n\
>> +Argument is optional filename.  Default filename is 'core.PROCESS_ID'."));

Pedro> Do the guidelines say anything about this?  I mean, PROCESS_ID is not
Pedro> user input, so I'm wondering whether it should be all caps, or whether
Pedro> it was better as it was.

Pedro> Otherwise looks fine.

The docs don't say much, but since the PID is a meta-syntactic variable,
I think this is the way to go.

Tom

Re: [RFA 03/12] Update core-related help strings

[Pedro Alves]

On 05/09/2018 09:31 PM, Tom Tromey wrote:
>>>>>> "Pedro" == Pedro Alves <palves@redhat.com> writes:
> 
> Pedro> On 04/30/2018 03:37 PM, Tom Tromey wrote:
>>> diff --git a/gdb/gcore.c b/gdb/gcore.c
>>> index 5ff4e6dc77..c53810049c 100644
>>> --- a/gdb/gcore.c
>>> +++ b/gdb/gcore.c
>>> @@ -611,7 +611,8 @@ _initialize_gcore (void)
>>> {
>>> add_com ("generate-core-file", class_files, gcore_command, _("\
>>> Save a core file with the current state of the debugged process.\n\
>>> -Argument is optional filename.  Default filename is 'core.<process_id>'."));
>>> +Usage: generate-core-file [FILENAME]\n\
>>> +Argument is optional filename.  Default filename is 'core.PROCESS_ID'."));
> 
> Pedro> Do the guidelines say anything about this?  I mean, PROCESS_ID is not
> Pedro> user input, so I'm wondering whether it should be all caps, or whether
> Pedro> it was better as it was.
> 
> Pedro> Otherwise looks fine.
> 
> The docs don't say much, but since the PID is a meta-syntactic variable,
> I think this is the way to go.

OK.

Thanks,
Pedro Alves

[RFA 07/12] Update help text for "jump" command

[Tom Tromey]

This updates the usage text for the "jump" command to conform to the
GNU style.

2018-04-29  Tom Tromey  <tom@tromey.com>

	* infcmd.c (_initialize_infcmd): Update help text.
---
 gdb/ChangeLog | 4 ++++
 gdb/infcmd.c  | 2 +-
 2 files changed, 5 insertions(+), 1 deletion(-)

diff --git a/gdb/infcmd.c b/gdb/infcmd.c
index 21772b6cff..86e5ef426b 100644
--- a/gdb/infcmd.c
+++ b/gdb/infcmd.c
@@ -3445,7 +3445,7 @@ Execution will also stop upon exit from the current stack frame."));
 
   c = add_com ("jump", class_run, jump_command, _("\
 Continue program being debugged at specified line or address.\n\
-Usage: jump <location>\n\
+Usage: jump LOCATION\n\
 Give as argument either LINENUM or *ADDR, where ADDR is an expression\n\
 for an address to start at."));
   set_cmd_completer (c, location_completer);
-- 
2.13.6

Re: [RFA 07/12] Update help text for "jump" command

[Pedro Alves]

On 04/30/2018 03:37 PM, Tom Tromey wrote:
> This updates the usage text for the "jump" command to conform to the
> GNU style.
> 
> 2018-04-29  Tom Tromey  <tom@tromey.com>
> 
> 	* infcmd.c (_initialize_infcmd): Update help text.

OK.

Thanks,
Pedro Alves

[RFA 10/12] Update help text in record-btrace.c

[Tom Tromey]

This updates the help text in record-btrace.c to conform to GNU
standards.

2018-04-29  Tom Tromey  <tom@tromey.com>

	* record-btrace.c (_initialize_record_btrace): Update help text.
---
 gdb/ChangeLog       | 4 ++++
 gdb/record-btrace.c | 4 ++--
 2 files changed, 6 insertions(+), 2 deletions(-)

diff --git a/gdb/record-btrace.c b/gdb/record-btrace.c
index 8736894243..dba5245832 100644
--- a/gdb/record-btrace.c
+++ b/gdb/record-btrace.c
@@ -3236,8 +3236,8 @@ replay."),
   add_prefix_cmd ("cpu", class_support, cmd_set_record_btrace_cpu,
 		  _("\
 Set the cpu to be used for trace decode.\n\n\
-The format is \"<vendor>:<identifier>\" or \"none\" or \"auto\" (default).\n\
-For vendor \"intel\" the format is \"<family>/<model>[/<stepping>]\".\n\n\
+The format is \"VENDOR:IDENTIFIER\" or \"none\" or \"auto\" (default).\n\
+For vendor \"intel\" the format is \"FAMILY/MODEL[/STEPPING]\".\n\n\
 When decoding branch trace, enable errata workarounds for the specified cpu.\n\
 The default is \"auto\", which uses the cpu on which the trace was recorded.\n\
 When GDB does not support that cpu, this option can be used to enable\n\
-- 
2.13.6

Re: [RFA 10/12] Update help text in record-btrace.c

[Pedro Alves]

On 04/30/2018 03:37 PM, Tom Tromey wrote:
> This updates the help text in record-btrace.c to conform to GNU
> standards.
> 
> 2018-04-29  Tom Tromey  <tom@tromey.com>
> 
> 	* record-btrace.c (_initialize_record_btrace): Update help text.

OK.

Thanks,
Pedro Alves

[RFA 11/12] Update help text in linux-fork.c

[Tom Tromey]

This updates some help text in linux-fork.c to conform to GNU
standards.

2018-04-29  Tom Tromey  <tom@tromey.com>

	* linux-fork.c (_initialize_linux_fork): Update help text.
---
 gdb/ChangeLog    | 4 ++++
 gdb/linux-fork.c | 4 ++--
 2 files changed, 6 insertions(+), 2 deletions(-)

diff --git a/gdb/linux-fork.c b/gdb/linux-fork.c
index 9ffab1ff6c..a674fe167a 100644
--- a/gdb/linux-fork.c
+++ b/gdb/linux-fork.c
@@ -787,8 +787,8 @@ Fork a duplicate process (experimental)."));
      process.  */
 
   add_com ("restart", class_obscure, restart_command, _("\
-restart <n>: restore program context from a checkpoint.\n\
-Argument 'n' is checkpoint ID, as displayed by 'info checkpoints'."));
+restart N: restore program context from a checkpoint.\n\
+Argument N is checkpoint ID, as displayed by 'info checkpoints'."));
 
   /* Delete checkpoint command: kill the process and remove it from
      the fork list.  */
-- 
2.13.6

Re: [RFA 11/12] Update help text in linux-fork.c

[Pedro Alves]

On 04/30/2018 03:37 PM, Tom Tromey wrote:
> This updates some help text in linux-fork.c to conform to GNU
> standards.
> 
> 2018-04-29  Tom Tromey  <tom@tromey.com>
> 
> 	* linux-fork.c (_initialize_linux_fork): Update help text.

OK.

Thanks,
Pedro Alves

[RFA 04/12] Update memattr.c help strings

[Tom Tromey]

This changes memattr.c to use the GNU style for help strings.

2018-04-29  Tom Tromey  <tom@tromey.com>

	* memattr.c (_initialize_mem): Update help string.
---
 gdb/ChangeLog |  4 ++++
 gdb/memattr.c | 14 +++++++-------
 2 files changed, 11 insertions(+), 7 deletions(-)

diff --git a/gdb/memattr.c b/gdb/memattr.c
index 8dad38b039..328a63a19d 100644
--- a/gdb/memattr.c
+++ b/gdb/memattr.c
@@ -603,27 +603,27 @@ _initialize_mem (void)
 Define attributes for memory region or reset memory region handling to\n\
 target-based.\n\
 Usage: mem auto\n\
-       mem <lo addr> <hi addr> [<mode> <width> <cache>],\n\
-where <mode>  may be rw (read/write), ro (read-only) or wo (write-only),\n\
-      <width> may be 8, 16, 32, or 64, and\n\
-      <cache> may be cache or nocache"));
+       mem LOW HIGH [MODE WIDTH CACHE],\n\
+where MODE  may be rw (read/write), ro (read-only) or wo (write-only),\n\
+      WIDTH may be 8, 16, 32, or 64, and\n\
+      CACHE may be cache or nocache"));
 
   add_cmd ("mem", class_vars, enable_mem_command, _("\
 Enable memory region.\n\
 Arguments are the code numbers of the memory regions to enable.\n\
-Usage: enable mem <code number>...\n\
+Usage: enable mem [CODE]...\n\
 Do \"info mem\" to see current list of code numbers."), &enablelist);
 
   add_cmd ("mem", class_vars, disable_mem_command, _("\
 Disable memory region.\n\
 Arguments are the code numbers of the memory regions to disable.\n\
-Usage: disable mem <code number>...\n\
+Usage: disable mem [CODE]...\n\
 Do \"info mem\" to see current list of code numbers."), &disablelist);
 
   add_cmd ("mem", class_vars, delete_mem_command, _("\
 Delete memory region.\n\
 Arguments are the code numbers of the memory regions to delete.\n\
-Usage: delete mem <code number>...\n\
+Usage: delete mem [CODE]...\n\
 Do \"info mem\" to see current list of code numbers."), &deletelist);
 
   add_info ("mem", info_mem_command,
-- 
2.13.6

Re: [RFA 04/12] Update memattr.c help strings

[Pedro Alves]

On 04/30/2018 03:37 PM, Tom Tromey wrote:
> This changes memattr.c to use the GNU style for help strings.
> 
> 2018-04-29  Tom Tromey  <tom@tromey.com>
> 
> 	* memattr.c (_initialize_mem): Update help string.
> ---
>  gdb/ChangeLog |  4 ++++
>  gdb/memattr.c | 14 +++++++-------
>  2 files changed, 11 insertions(+), 7 deletions(-)
> 
> diff --git a/gdb/memattr.c b/gdb/memattr.c
> index 8dad38b039..328a63a19d 100644
> --- a/gdb/memattr.c
> +++ b/gdb/memattr.c
> @@ -603,27 +603,27 @@ _initialize_mem (void)
>  Define attributes for memory region or reset memory region handling to\n\
>  target-based.\n\
>  Usage: mem auto\n\
> -       mem <lo addr> <hi addr> [<mode> <width> <cache>],\n\
> -where <mode>  may be rw (read/write), ro (read-only) or wo (write-only),\n\
> -      <width> may be 8, 16, 32, or 64, and\n\
> -      <cache> may be cache or nocache"));
> +       mem LOW HIGH [MODE WIDTH CACHE],\n\
> +where MODE  may be rw (read/write), ro (read-only) or wo (write-only),\n\
> +      WIDTH may be 8, 16, 32, or 64, and\n\
> +      CACHE may be cache or nocache"));
>  
>    add_cmd ("mem", class_vars, enable_mem_command, _("\
>  Enable memory region.\n\
>  Arguments are the code numbers of the memory regions to enable.\n\
> -Usage: enable mem <code number>...\n\
> +Usage: enable mem [CODE]...\n\
>  Do \"info mem\" to see current list of code numbers."), &enablelist);
>  
>    add_cmd ("mem", class_vars, disable_mem_command, _("\
>  Disable memory region.\n\
>  Arguments are the code numbers of the memory regions to disable.\n\
> -Usage: disable mem <code number>...\n\
> +Usage: disable mem [CODE]...\n\
>  Do \"info mem\" to see current list of code numbers."), &disablelist);
>  
>    add_cmd ("mem", class_vars, delete_mem_command, _("\
>  Delete memory region.\n\
>  Arguments are the code numbers of the memory regions to delete.\n\
> -Usage: delete mem <code number>...\n\
> +Usage: delete mem [CODE]...\n\
>  Do \"info mem\" to see current list of code numbers."), &deletelist);
>  

I was surprised and confused with the references to "code" and
"code numbers" here.  These are just the numbers as displayed
in the first column of "info mem", right?  How about changing
the references to "code numbers" and "CODE" above to 
numbers or IDs?  The manuals uses "nums".

Thanks,
Pedro Alves

Re: [RFA 04/12] Update memattr.c help strings

[Tom Tromey]

>>>>> "Pedro" == Pedro Alves <palves@redhat.com> writes:

>> add_cmd ("mem", class_vars, delete_mem_command, _("\
>> Delete memory region.\n\
>> Arguments are the code numbers of the memory regions to delete.\n\
>> -Usage: delete mem <code number>...\n\
>> +Usage: delete mem [CODE]...\n\
>> Do \"info mem\" to see current list of code numbers."), &deletelist);
>> 

Pedro> I was surprised and confused with the references to "code" and
Pedro> "code numbers" here.  These are just the numbers as displayed
Pedro> in the first column of "info mem", right?  How about changing
Pedro> the references to "code numbers" and "CODE" above to 
Pedro> numbers or IDs?  The manuals uses "nums".

I went with IDs, like:

      add_cmd ("mem", class_vars, delete_mem_command, _("\
    Delete memory region.\n\
    Arguments are the identifiers of the memory regions to delete.\n\
    Usage: delete mem [ID]...\n\
    Do \"info mem\" to see current list of IDs."), &deletelist);

Tom

Re: [RFA 04/12] Update memattr.c help strings

[Pedro Alves]

On 05/09/2018 09:34 PM, Tom Tromey wrote:
>>>>>> "Pedro" == Pedro Alves <palves@redhat.com> writes:
> 
>>> add_cmd ("mem", class_vars, delete_mem_command, _("\
>>> Delete memory region.\n\
>>> Arguments are the code numbers of the memory regions to delete.\n\
>>> -Usage: delete mem <code number>...\n\
>>> +Usage: delete mem [CODE]...\n\
>>> Do \"info mem\" to see current list of code numbers."), &deletelist);
>>>
> 
> Pedro> I was surprised and confused with the references to "code" and
> Pedro> "code numbers" here.  These are just the numbers as displayed
> Pedro> in the first column of "info mem", right?  How about changing
> Pedro> the references to "code numbers" and "CODE" above to 
> Pedro> numbers or IDs?  The manuals uses "nums".
> 
> I went with IDs, like:
> 
>       add_cmd ("mem", class_vars, delete_mem_command, _("\
>     Delete memory region.\n\
>     Arguments are the identifiers of the memory regions to delete.\n\
>     Usage: delete mem [ID]...\n\
>     Do \"info mem\" to see current list of IDs."), &deletelist);

Great, thanks.

Thanks,
Pedro Alves

[RFA 01/12] Fix help and documentation for inferior commands

[Tom Tromey]

This changes inferior.c to add Usage lines for all commands, and to
change how "metasyntactic variables" are written to conform to GNU
style.

While doing this I noticed that the manual doesn't document the
argument to "info inferiors", so I've added that as well.

ChangeLog
2018-04-27  Tom Tromey  <tom@tromey.com>

	* inferior.c (initialize_inferiors): Update help strings.

doc/ChangeLog
2018-04-27  Tom Tromey  <tom@tromey.com>

	* gdb.texinfo (Inferiors and Programs): Document argument to "info
	inferiors".
---
 gdb/ChangeLog       |  4 ++++
 gdb/doc/ChangeLog   |  5 +++++
 gdb/doc/gdb.texinfo |  4 +++-
 gdb/inferior.c      | 18 ++++++++++++------
 4 files changed, 24 insertions(+), 7 deletions(-)

diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index 28f083f96e..a25ada6e28 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -2708,9 +2708,11 @@ To find out what inferiors exist at any moment, use @w{@code{info
 inferiors}}:
 
 @table @code
-@kindex info inferiors
+@kindex info inferiors [ @var{ID}@dots{} ]
 @item info inferiors
 Print a list of all inferiors currently being managed by @value{GDBN}.
+By default all inferiors are printed, but an argument can be used to
+limit the display to just the requested inferiors.
 
 @value{GDBN} displays for each inferior (in this order):
 
diff --git a/gdb/inferior.c b/gdb/inferior.c
index d7122fcfad..ec2f985919 100644
--- a/gdb/inferior.c
+++ b/gdb/inferior.c
@@ -996,12 +996,15 @@ initialize_inferiors (void)
   /* The architecture will be initialized shortly, by
      initialize_current_architecture.  */
 
-  add_info ("inferiors", info_inferiors_command, 
-	    _("IDs of specified inferiors (all inferiors if no argument)."));
+  add_info ("inferiors", info_inferiors_command,
+	    _("Print a list of inferiors being managed.\n\
+Usage: info inferiors [ID]...\n\
+If IDs are specified, the list is limited to just those inferiors.\n\
+By default all inferiors are displayed."));
 
   c = add_com ("add-inferior", no_class, add_inferior_command, _("\
 Add a new inferior.\n\
-Usage: add-inferior [-copies <N>] [-exec <FILENAME>]\n\
+Usage: add-inferior [-copies N] [-exec FILENAME]\n\
 N is the optional number of inferiors to add, default is 1.\n\
 FILENAME is the file name of the executable to use\n\
 as main program."));
@@ -1013,22 +1016,25 @@ Usage: remove-inferiors ID..."));
 
   add_com ("clone-inferior", no_class, clone_inferior_command, _("\
 Clone inferior ID.\n\
-Usage: clone-inferior [-copies <N>] [ID]\n\
+Usage: clone-inferior [-copies N] [ID]\n\
 Add N copies of inferior ID.  The new inferior has the same\n\
 executable loaded as the copied inferior.  If -copies is not specified,\n\
 adds 1 copy.  If ID is not specified, it is the current inferior\n\
 that is cloned."));
 
   add_cmd ("inferiors", class_run, detach_inferior_command, _("\
-Detach from inferior ID (or list of IDS)."),
+Detach from inferior ID (or list of IDS).\n\
+Usage; detach inferiors ID..."),
 	   &detachlist);
 
   add_cmd ("inferiors", class_run, kill_inferior_command, _("\
-Kill inferior ID (or list of IDs)."),
+Kill inferior ID (or list of IDs).\n\
+Usage: kill inferiors ID..."),
 	   &killlist);
 
   add_cmd ("inferior", class_run, inferior_command, _("\
 Use this command to switch between inferiors.\n\
+Usage: inferior ID\n\
 The new inferior ID must be currently known."),
 	   &cmdlist);
 
-- 
2.13.6

Re: [RFA 01/12] Fix help and documentation for inferior commands

[Eli Zaretskii]

> From: Tom Tromey <tom@tromey.com>
> Cc: Tom Tromey <tom@tromey.com>
> Date: Mon, 30 Apr 2018 08:37:20 -0600
> 
> While doing this I noticed that the manual doesn't document the
> argument to "info inferiors", so I've added that as well.

Thanks.

>  @table @code
> -@kindex info inferiors
> +@kindex info inferiors [ @var{ID}@dots{} ]

"ID" should be in lower-case.  (It will be rendered in caps in Info,
but not in the printed output, where it will be typeset in the slant
typeface.)

> +By default all inferiors are printed, but an argument can be used to
> +limit the display to just the requested inferiors.

This should reference @var{id} and explain what the "id" there is.
Someone might think it's a PID, for example.

Re: [RFA 01/12] Fix help and documentation for inferior commands

[Pedro Alves]

On 04/30/2018 04:26 PM, Eli Zaretskii wrote:
>> From: Tom Tromey <tom@tromey.com>
>> Cc: Tom Tromey <tom@tromey.com>
>> Date: Mon, 30 Apr 2018 08:37:20 -0600
>>
>> While doing this I noticed that the manual doesn't document the
>> argument to "info inferiors", so I've added that as well.
> 
> Thanks.
> 
>>  @table @code
>> -@kindex info inferiors
>> +@kindex info inferiors [ @var{ID}@dots{} ]
> 
> "ID" should be in lower-case.  (It will be rendered in caps in Info,
> but not in the printed output, where it will be typeset in the slant
> typeface.)
> 
>> +By default all inferiors are printed, but an argument can be used to
>> +limit the display to just the requested inferiors.
> 
> This should reference @var{id} and explain what the "id" there is.
> Someone might think it's a PID, for example.

I think it'll also to good to say that it's a space-separated
list of IDs, like we say in the "info threads" help and documentation.
See thread-id-list / "thread ID lists", and "breakpoint lists" in
the manual for examples.

Thanks,
Pedro Alves

Re: [RFA 01/12] Fix help and documentation for inferior commands

[Tom Tromey]

>>>>> "Eli" == Eli Zaretskii <eliz@gnu.org> writes:

>> From: Tom Tromey <tom@tromey.com>
>> Cc: Tom Tromey <tom@tromey.com>
>> Date: Mon, 30 Apr 2018 08:37:20 -0600
>> 
>> While doing this I noticed that the manual doesn't document the
>> argument to "info inferiors", so I've added that as well.

Eli> Thanks.

>> @table @code
>> -@kindex info inferiors
>> +@kindex info inferiors [ @var{ID}@dots{} ]

Eli> "ID" should be in lower-case.  (It will be rendered in caps in Info,
Eli> but not in the printed output, where it will be typeset in the slant
Eli> typeface.)

>> +By default all inferiors are printed, but an argument can be used to
>> +limit the display to just the requested inferiors.

Eli> This should reference @var{id} and explain what the "id" there is.
Eli> Someone might think it's a PID, for example.

How about like this:

    @kindex info inferiors [ @var{id}@dots{} ]
    @item info inferiors
    Print a list of all inferiors currently being managed by @value{GDBN}.
    By default all inferiors are printed, but the argument -- a space
    separate list of inferior numbers -- can be used to limit the display
    to just the requested inferiors.

This doesn't refer to @var{id} but I didn't see a clean way to do that.

Tom

Re: [RFA 01/12] Fix help and documentation for inferior commands

[Eli Zaretskii]

> From: Tom Tromey <tom@tromey.com>
> Cc: Tom Tromey <tom@tromey.com>,  gdb-patches@sourceware.org
> Date: Wed, 09 May 2018 14:29:28 -0600
> 
> >> @table @code
> >> -@kindex info inferiors
> >> +@kindex info inferiors [ @var{ID}@dots{} ]
> 
> Eli> "ID" should be in lower-case.  (It will be rendered in caps in Info,
> Eli> but not in the printed output, where it will be typeset in the slant
> Eli> typeface.)
> 
> >> +By default all inferiors are printed, but an argument can be used to
> >> +limit the display to just the requested inferiors.
> 
> Eli> This should reference @var{id} and explain what the "id" there is.
> Eli> Someone might think it's a PID, for example.
> 
> How about like this:
> 
>     @kindex info inferiors [ @var{id}@dots{} ]
>     @item info inferiors
>     Print a list of all inferiors currently being managed by @value{GDBN}.
>     By default all inferiors are printed, but the argument -- a space
>     separate list of inferior numbers -- can be used to limit the display
>     to just the requested inferiors.

Yes, thanks.

> This doesn't refer to @var{id} but I didn't see a clean way to do that.

Like this:

  ... but the argument @var{id}@dots{} -- a space separated list ...

(Note: "separated", not "separate".)

Re: [RFA 00/12] Small help text tweaks

[Eli Zaretskii]

> From: Tom Tromey <tom@tromey.com>
> Date: Mon, 30 Apr 2018 08:37:19 -0600
> 
> I've long understood the GNU style for "metasyntactic variables" --
> text that is a placeholder for some value -- to be to write them in
> all caps.  For example, from "gdb --help":
> 
>   --core=COREFILE    Analyze the core dump COREFILE.
> 
> However, while researching for this post, I couldn't actually find
> this in the GNU coding standards -- I thought it was there, but the
> closest I could find was in the Emacs Lisp manual.

It's actually a simple side effect of how Texinfo formats @var{..} in
Info output.  I think.

Re: [RFA 00/12] Small help text tweaks

[Tom Tromey]

>>>>> "Eli" == Eli Zaretskii <eliz@gnu.org> writes:

Eli> It's actually a simple side effect of how Texinfo formats @var{..} in
Eli> Info output.  I think.

Yeah.  I just thought this used to be in the coding standards, and now I
can't find it there.  I do see it here though: (info "(elisp) Documentation Tips");
and it is definitely a widespread GNU style in "--help" output -- and
also elsewhere in gdb help strings.

Tom